Maclvory User's Guide 

Preface 

Maclvory provides the benefits of symbolic processing along with the features of a 
Macintosh personal computer. Before using your Maclvory, read "Introduction to 
Maclvory Machines" (this will familiarize you with the system). Then, read the 
user documentation supplied by Apple, and the disk drive and monitor manufactur- 
ers, so that you will feel confident about using the Macintosh computer, and the 
Maclvory system's components. 

Once you are familiar with your Maclvory, its components, and the Macintosh user 
interface, return to this manual. Begin by reading and following the steps in "Get- 
ting Started with Maclvory" to position and power up your Maclvory System. 

This book is divided into two main sections: a user's manual and a programmer's 
reference. The user's manual can help you to get started using Maclvory, and pro- 
vides information on some common Maclvory operations. The programmer's refer- 
ence provides information on how to use features of the Macintosh operating sys- 
tem from Genera and other topics for programmers who are developing Maclvory 
applications. 

You may also want to refer to this additional documentation: 

• For information about adapting programs written on Symbolics 3600-series ma- 
chines to Maclvory, see the section "Porting Genera Applications to Ivory Ma- 
chines". 

• For information about the Genera 8.0 software and how it differs from Genera 
7.4 Ivory, see Genera 8.0 Release Notes. For information about Symbolics ma- 
chines and the Genera software development environment, refer to the books 
contained within the Genera documentation set. New Symbolics users should 
refer to these titles first: 

° Genera Workbook 

° Site Operations 

° Genera User's Guide 



Overview of Maclvory 

The Maclvory system makes Symbolics' Genera software environment, which en- 
ables the comprehensive development, prototyping, and delivery of applications, 
available to Apple Macintosh II users. 

Whenever possible, Maclvory maintains the Macintosh user interface paradigm for 
video, I/O processing and communications. The Maclvory board set plugs directly 
into the Macintosh II with no other system modifications required. Genera applica- 
tions can be "opened" under MacOS just like any other Macintosh window. 
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Maclvory software basically consists of two parts: Code that runs on the Ivory pro- 
cessor and code that runs on the Macintosh. The two processors communicate with 
each other through a special region of memory that they both access. Maclvory 
has exclusive use of a memory region allocated to it by the Macintosh when the 
Macintosh is powered on or restarted, and the Macintosh uses the rest of memory. 
All input/output is handled through the Macintosh. 

On the Ivory side, the code provided (written in Lisp) consists of: 

• A Remote Procedure Call (RPC) interface. 

• Genera modified as necessary to use the MacOS for all input/output, including 
keyboard, mouse, disk, Ethernet, and console screen accesses. 

• IFEP code modified similarly. (The IFEP is the part of Genera software involved 
with booting and initializing a world. Historically, this code resided in read-only 
memory on the Front End Processor of a Symbolics machine; therefore the name 
IFEP, with I standing for Ivory.) 

On the Macintosh side, the code provided (written in C) consists of: 

• Code to initialize the Maclvory and the IFEP. 

• Life-Support code required to support Maclvory. 



• 



A Macintosh application that allows users to access applications running on 
Ivory. 



Macintosh/Ivory Communication 

Communication is based on a shared memory, readable and writable by both the 
guest (Ivory) and the host (Macintosh) processors. Outside of shared memory, each 
processor has its own memory space. This memory space is allocated to each pro- 
cessor when the Macintosh II is booted. 

There is no shared disk space: The disk is partitioned into Ivory space and Macin- 
tosh space. (Ivory disk space is further partitioned into FEP file space and Lisp- 
Machine File Space just as it would be on a 3600 or XL400, but this is transpar- 
ent to application users.) 

There are two levels of communication between the Macintosh and Ivory: 

• In shared memory, a buffered channel exists between drivers on the Macintosh 
and on Ivory for those operations requiring maximum performance, such as disk 
I/O and network communication. 

• A remote procedure call (RPC) interface for general-purpose input/output. 

The host (Macintosh running MacOS) is primary in the sense that it is booted 



Page 893 



first and the guest (Ivory), looks like just one of the several application programs 
that the user can run. A Macintosh application program runs when the user wants 
to make use of Ivory. This program boots Ivory, and gives Ivory control over the 
keyboard, mouse and all or part of the screen. After that, the Ivory runs continu- 
ously, staying up between visits by the user, unless the user explicitly reboots the 
Ivory or reboots the Macintosh. 

Communication between guest and host applications is managed by the Remote 
Procedure Call (RFC) protocol. The same protocol also allows Ivory to access the 
MacOS, and vice versa. 



Software Components of Maclvory 

In addition to standard Genera, software components for Maclvory include: 

• RFC, the Remote Frocedure Call facility 

• The remote window facility built on RFC that allows the Genera window system 
to use the screen, keyboard, and mouse of the host Macintosh instead of directly 
manipulating a 3600-series machine's own local screen, keyboard, and mouse 

• A user interface system that is adaptable to Genera style or Macintosh style 

• Interface to the Macintosh toolbox 

• Support for accessing Macintosh files 

• Support for Macintosh peripherals, such as Ethernet, tape and serial lines 

• Support for some Macintosh data and file formats 

User's Manual for Maclvory 

Introduction to Maclvory Machines 

Maclvory machines integrate the Genera software environment with the Apple 
Macintosh II (including its operating system and the Toolbox) this way: 

• The Genera software environment accelerates programmer productivity and pro- 
vides the ability to do complex, real-world problem solving. 

• The Macintosh offers a stylish and easy-to-learn user interface, along with ac- 
cess to a wide variety of third-party applications. 

Maclvory provides full integration of these two systems; it is designed to combine 
the advantages of each, while delivering the benefits of both. 
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Maclvory relies on the Macintosh processor for I/O services such as keyboard, dis- 
play, and disk access. All of Macintosh's system and toolbox entry points can be 
called from Lisp using Remote Procedure Calls (RPC). Additionally, Genera facili- 
ties (Dynamic Windows, for example) use Macintosh facilities, and Maclvory makes 
full use of the Macintosh for graphics. This kind of integration means that exist- 
ing Genera applications — developed on the Symbolics 3600 series of machines — 
can readily take advantage of Macintosh features. 

Maclvory enables you to design applications that employ either the Macintosh user 
interface (UI), the Genera user interface, or both. Furthermore, without changing 
your program, you can allow end users to make their own UI choices. Maclvory 
doesn't mandate a user interface style for your applications; you are free to create 
your own. 



Maclvory Software Description 

Maclvory software consists of: 

Genera 8.1 The Genera environment adapted to run on the Ivory proces- 

sor; both a development and a delivery version are available. 
This software is contained within the Symbolics Distribution 
World and is distributed on disk and QlC-lOO tapes. 

Maclvory Support Software 

To provide Maclvory with the basic I/O services it needs to 
run Genera, and to facilitate high-level communication between 
the two processors by using a Remote Procedure Call (RPC) 
mechanism. This software is distributed on floppy diskettes. 



Getting Started with Maclvory 

Symbolics Service Personnel will configure and install your Maclvory System. After 
it is installed, perform these tasks: 

1. Following each manufacturer's directions to ensure that you leave appropriate 
clearance for cooling, position the Macintosh computer and the external disk 
drive (if your system is equipped with one) conveniently in your workspace. 

Position the 19" monitor on either side of the Macintosh II or on a stand over 
the Macintosh II, as the manufacturer recommends. 

Warning: Be sure to position the 19" monitor so that there is at least an inch 
between the monitor and the Macintosh II to ensure adequate ventilation and 
avoid overheating. Do not place the 19" monitor near heat sources such as ra- 
diators or in an area subject to direct sunlight. 

2. Make sure that the Symbolics keyboard template has been placed over the 
keys. 
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3. Power up (plug in and turn on) the external disk drive (if your system is 
equipped with one) and the Macintosh computer according to each manufac- 
turer's instructions. 

Note: At power up, you will momentarily see the Apple "Happy Mac" on your Mac- 
intosh screen, indicating that the Macintosh is starting up from the disk drive. 
You will also see a symbol in the lower left-hand corner of your screen that indi- 
cates the presence of pre-installed Ivory "life-support" software on the disk drive. 



Controlling the Ivory Coprocessor on a Maclvory 

When you first power on the Macintosh and start up an Ivory application (by dou- 
ble-clicking on the Genera icon, for example), the Ivory coprocessor is initialized, 
and Genera is cold booted. This may take a few minutes. 

Once the Ivory coprocessor has been initialized and Genera has been cold booted 
(by the first Ivory application that needs it), you can open and quit that applica- 
tion — and other Ivory applications — as quickly and easily as you do ordinary 
(non-Ivory-dependent) Macintosh applications. 

When you restart the Macintosh by choosing Restart from the Special menu (avail- 
able from the Finder), this initializes the Macintosh processor, but preserves the 
state of the Ivory coprocessor's virtual memory. 

Because the Ivory coprocessor's virtual memory is unaffected when you restart the 
Macintosh computer, the Ivory coprocessor does not need initializing — and Gen- 
era does not need cold booting — each time you restart the Macintosh computer. 

When you open an Ivory application, it checks to see whether the Ivory coprocessor 
can be warm booted (that is, whether the Ivory coprocessor's virtual memory has 
some state), or whether it must be cold booted. If the Ivory coprocessor can be 
warm booted, you have two options: 

1. Click on "Restart Lisp" when the alert box appears. This opens the application 
without initializing the Ivory coprocessor or cold booting Genera. Clicking on 
"Restart Lisp" preserves the contents of Ivory's virtual memory but warm 
boots Ivory, resetting its processes and closing its network connections. 

2. Click on "Cold Boot Lisp" when the alert box appears. This opens the applica- 
tion, initializes the Ivory coprocessor, and cold boots Genera. Clicking on 
"Cold Boot Lisp" means the contents of Ivory's virtual memory will be lost. 

If there is not enough state available to warm boot the Ivory coprocessor, then the 
application itself causes the Ivory coprocessor to initialize, and Genera to cold 
boot. 

More information is available about cold booting and warm booting. See the sec- 
tion "Cold Booting". See the section "Warm Booting". 
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Using the Ivory Menu 

Once you have opened an Ivory application and it is running, you can control it 
and the Ivory coprocessor by using the Ivory menu in the menu bar at the top of 
your Macintosh screen. 

Tables 1 and 2 describe the Ivory menu items by showing you their Symbolics 
3600-series machine equivalents. 



Ivory Menu Item (invoked 
while running Lisp) 


3600-Series Machine Equivalent 


Restart Lisp 


Halt Machine (Command Processor Command) 
Start (FEP Command) 


Cold Boot Lisp 


Halt Machine (Command Processor Command) 
Press RESET on the machine's front panel 
Hello (FEP Command) 
Boot (FEP Command) 


Transfer to FEP 


Halt Machine (Command Processor Command) 


Restart FEP 


Halt Machine (Command Processor Command) 
Reset FEP (FEP Command) 


Cold Boot FEP 


Halt Machine (Command Processor Command) 
Press RESET on the machine's front panel 


Shut Down 


Halt Machine (Command Processor Command) 
Shutdown (FEP Command) 


Hide/Show Cold Load 


No equivalent; causes the Cold Load 
Stream window to move back or forward. 


Enable/Disable Network 


No equivalent; selects whether 

Ivory (Enable) or the Macintosh (Disable) has 

access to the Ethernet cable. 



Table 1. The Meaning of Ivory Menu Items (while Lisp is Running) 



Using the Genera Application on a Maclvory 

The Genera application is a program that provides Maclvory users with the tradi- 
tional Symbolics user interface to the Genera software environment. Like other 
third-party supplied Macintosh applications, the Genera application can be invoked 
with the Macintosh user interface. 
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Ivory Menu Item (invoked 
from the FEP) 


3600-Series Machine Equivalent 


Transfer to Lisp 


Continue (FEP Command) 


Restart Lisp 


Hello (FEP Command) if flod files need scanning 
Start (FEP Command) 


Cold Boot Lisp 


Press RESET on the machine's front panel 
Hello (FEP Command) 
Boot (FEP Command) 


Restart FEP 


Reset FEP (FEP Command) 


Cold Boot FEP 


Press RESET on the machine's front panel 


Shut Down 


Shutdown (FEP Command) 


Hide/Show Cold Load 


No equivalent; causes the Cold Load 
Stream window to move back or forward. 


Enable/Disable Network 


No equivalent; selects whether 

Ivory (Enable) or the Macintosh (Disable) has 

access to the Ethernet cable. 



Table 2. The Meaning of Ivory Menu Items (while in the FEP) 



Start up the Genera application by double-clicking on the Genera icon. The Genera 
application lets your Maclvory emulate a Symbolics 3600-series machine's console. 
On a Maclvory, however, the Genera window system can use all — or just part — 
of the available screen. 

You can use the Macintosh's user interface software (for example, MultiFinder) to 
select between different Macintosh applications, including Genera. (For information 
about how to use the Macintosh system software, refer to the Apple user documen- 
tation supplied with your Maclvory system.) 

Note: If you cannot find the mouse cursor while in Genera, press the Power On 
key (at the upper right-hand corner) on the Apple Extended Keyboard. This will 
cause the cursor to reappear at the Apple symbol on the Menu bar. 

Caution: The Ivory Breath of Life Application (BOL FEP) which you see in your 
Maclvory Applications folder is used for initializing FEP file systems only. Experi- 
menting with it while Lisp is running damages your Lisp system in such a way 
that you cannot warm boot. Do not experiment with it. 



Accessing the Macintosh File System 
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Files on the Maclvory's Macintosh file system can be accessed from Genera using 
pathnames that follow Macintosh syntactic conventions. 

To access the Macintosh file system from Genera on the local Maclvory, use this 
format: 

HOST : Volume : Folder : Folder : Filename 
In this format, 

• The word HOST is literal; it refers to the local Macintosh file system, similar to 
the way the word FEP refers to the local FEP files system on 3600-series ma- 
chines. 

• Volume is the Macintosh volume name (the name that's displayed under the disk 
icon on the Macintosh desktop). 

• Folder names the directory (or subdirectory) in which the file Filename resides. 

To access the Maclvory's Macintosh file system from Genera on a remote 
Maclvory or Symbolics 3600-series machine, use this format (note the addition of a 
vertical bar in the pathname): 

Maclvory-Host-Name I HOST : Volume : Folder : Folder : Filename 

Here, 

• Maclvory-Host-Name names the Maclvory host whose Macintosh file system you 
want to access. 

The Macintosh syntax uses colons to separate pathname components. To show a di- 
rectory on the local Macintosh file system: 

Command: Show Directory (files [default Y:>Dodds>pending>*.*. newest]) 
HOST :dsk:zippy :pinhead:* 



HOST :dsk:zippy :pinhead:* 

3292 free, 64733/68025 used (blocks of 4608 8-bit bytes) 
(773 files in 154 dirs) 

complex 5 640(8) 11/03/89 22:49:40 

simple 5 640(8) 11/03/89 23:39:58 

test-file. sab 5 1250(8) 11/03/89 22:54:59 

15 blocks in 3 files 



Macintosh Pathname Completion 
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Genera's completion facilities can access the file systems of various hosts, includ- 
ing Macintosh computers. To perform Macintosh pathname completion, Genera 
looks in the Macintosh's file system and returns a new, possibly more specific 
string than the one that you have entered, expanding any unambiguous abbrevia- 
tions in a Macintosh host-dependent fashion. 

Insert an asterisk (*) to get wildcard possibilities (including devices) within Macin- 
tosh pathnames. Use the c-/ and c-? keystrokes to see multiple possibilities for 
what you have already typed. For more information about using these keystrokes, 
see the section "c-? and c-/". For information about quoting special characters (*, 
for example), see the section "Macintosh Pathname Quoting". 



Macintosh Pathname Quoting 

To the Macintosh, all characters are legal in pathnames and only colons delimit 
directories. This means, for example, that asterisks may appear as a component of 
a Macintosh pathname. Since Genera considers asterisk to be a wildcard, you can- 
not type a Macintosh pathname containing an asterisk without quoting it. There- 
fore, when typing a pathname such as 

HOST :i;oZM/ne:*Graphics: picture 

you need to quote the asterisk to indicate to Genera that it is not a wildcard. Cir- 
cle-Plus (®, sv-sh-+) is the quote character. So you would actually type: 

Host : volume : ®*Graphi cs : pi cture 

This also means that when Genera prints a Macintosh pathname that has an aster- 
isk as part of its name, it quotes the asterisk using the Circle-Plus character. 

The Symbohcs Keyboard for Maclvory 

The Symbolics keyboard is optimized for Lisp programmers, and for running Gen- 
era. For information about installing a Symbolics keyboard for a Maclvory, see the 
section "Installing a Symbolics Keyboard and Three-Button Mouse on a Maclvory". 
For information about using the Symbolics keyboard, see the section "Index of Spe- 
cial Function Keys". 

For more information, see the section "Using the Symbolics Keyboard with Native 
Macintosh Applications". 

Changing the Keyboard Mappings on a Maclvory 

Changing the Shift Key Order (Controi, Meta, Shift) on Appie Keyboards 

You can change the shift key order on an Apple Keyboard following these steps: 

1. Select Keyboard from the Options menu. 

2. Select Common Settings. 
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3. Click on the appropriate shift key order. 

Reconfiguring Keyboard IVlappings 

You can reconfigure the settings on either the Apple or Symbolics keyboard follow- 
ing these steps: 

1. Select Keyboard from the Options menu. 

2. Select Keyboard Control. 

The keyboard control menu appears enabling you to reconfigure your keyboard 
mappings (see Figure ! ). 

Keyboard Control (Symbolics) 



FUNCTION 


ESCAPE 


REFFiESH 


■ 


• 


▲ 


CLEAFi INPUT 


SUSPEND 


RESUME 


ABORT 


NETWORK 
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HELP 
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TAB 
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BACK 

SPACE 


PAGE 


COMPLETE 


SELECT 


RUB OUT 
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s 
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F 


Q 


H 


J 


K 


L 






RETURN 


LINE 


END 


CAPS 
LOCK 


SYMBOL 


SHIFT 


z 


X 


c 


V 


B 


N 


M 


< 
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/ 


SHIFT 


SYMBOL 


REPEAT 


MODE 
LOCK 


HYPER 


SUPER 


META 


CONTROL 




CONTROL 


META 


SUPER 


HYPER 


SCROLL 



Edit Mappings Hardcopy Key Test Revert Save Differences Set Keyboard Show Differences Typing Test Where Is 



Figure 90. Keyboard Control Menu 



You can reconfigure your keyboard mappings by clicking Left on Edit Mappings 
and specifying All at the prompt. The keyboard mappings for your keyboard ap- 
pears as in Figure !. 

You can change the keyboard mapping for each key by clicking Left on the current 
setting for the key and specifying a new setting. For example, you can change the 
current setting of the key sequence Symbol A from Unassigned to S: 

1. Click Left on Unassigned. 

2. Specify S. 

3. Press RETURN 

You can now obtain the letter S by pressing Symbol A. You can change this key- 
board mapping again following the preceding steps. You can also use the Keyboard 
Control menu for: 
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Keyboard Control (Symbolics) 
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Edit Mappings Hardcopy Key Test Revert Save Differences Set Keyboard Show Differences Typing Test Where Is 

ft + Return Return 
lol + Return Return 
ft + Return Return 

Conplete Conplete 
ft + Conplete Conplete 
lol + Conplete Conplete 
ft + Conplete Conplete 



Synbol + Sh 



Synbol + Sh 



Synbol + Sh 



Hetw. 
ft + Hetw. 
jol + Hetw. 
ft + Hetw. 

R a 
ft + R R 
jol + R 
ft + R 
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G 

Shift + G 
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ft + D D 
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Figure 91. Reconfiguring Keyboard Mappings 



Hardcopying the Keyboard Layout 

Displaying Raw Keyboard and Mouse Transitions 

Resetting the Keyboard Mapping to a Standard Mapping 

Saving the Differences in Keyboard Mappings 

Setting the Keyboard to a Default or Predefined Keyboard 

Showing the Differences in Keyboard Mappings 

Displaying Key Mappings 

Determining the Key Mapping that Generates a Character 



Hardcopying the Keyboard Layout 

You can hardcopy your current keyboard layout and mappings following these 
steps: 



1. Select Keyboard from the Options menu. 
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2. Select Keyboard Control. 

3. click Left on Hardcopy for hardcopying the keyboard layout using default 
printer settings. You can customize the printer settings by clicking Right on 
Hardcopy and specifying: 

• The printer on which you are printing the keyboard mappings. 

• The print orientation (Portrait or Landscape). 

• Whether you include legends or mappings. 

• Whether you include codes (Octal, Decimal, or Hex). 

Displaying Raw Keyboard and Mouse Transitions 

You can determine whether your keyboard operates correctly by using the Key Test 
option. This option displays the key sequence generated when you press a key. You 
can start the Key Test option following these steps: 

1. Select Keyboard from the Options menu. 

2. Select Keyboard Control. 

3. Chck Left on Key Test. 

Resetting the Keyboard Mapping to a Standard Mapping 

You can set your customized keyboard mappings to a standard keyboard mapping 
following these steps: 

1. Select Keyboard from the Options menu. 

2. Select Keyboard Control. 

3. Click Left on Revert. 

Saving thie Differences in Keyboard Mappings 

You can place the differences between customized keyboard mappings and standard 
keyboard mappings on the kill ring following these steps: 

1. Select Keyboard from the Options menu. 

2. Select Keyboard Control. 

3. Click left on Save Differences. 
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Setting the Keyboard to a Default or Predefined Keyboard 

You can set your keyboard to either the default Symbohcs keyboard or to another 
predefined keyboard following these steps: 

1. Select Keyboard from the Options menu. 

2. Select Keyboard Control. 

3. You can set your keyboard to the default by clicking Left on Set Keyboard, or 
you can specify another predefined keyboard by clicking Right on Set Key- 
board. 

Shiowing ttie Differences in Keyboard Mappings 

You can show the differences in mappings between your keyboard and the standard 
keyboard following these steps: 

1. Select Keyboard from the Options menu. 

2. Select Keyboard Control. 

3. Click left on Show Differences. 

Displaying Key iViappings 

You can display the mappings for keys on your keyboard following these steps: 

1. Select Keyboard from the Options menu. 

2. Select Keyboard Control. 

3. Chck left on Typing Test. 

You can now press any key and see the current keyboard mapping on your screen. 

Determining ttie Key i\/lapping ttiat Generates a Ctiaracter 

You can determine how a character is generated following these steps: 

1. Select Keyboard from the Options menu. 

2. Select Keyboard Control. 

3. Chck left on Where Is. 

4. Specify a character. 

The system displays the key sequence necessary for generating the character you 
specify. 
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Using the Print Spooler with Genera 

To spool an LGP2/LGP3 printer from a Maclvory machine, you need one 8-pin- 
male-to-25-pin-male cable with a null modem in it. Alternatively, you can use any 
combination of cables that provides you with this configuration. 

1. Plug the printer into one of the serial ports on the back of the Macintosh 
computer. You can run the printer from the modem port (UNIT 0) or the print- 
er port (Unit 1). 

2. Edit the printer's Namespace Object as follows: 

Interface: SERIAL 

Interface Options: UNIT n BAUD 9600 PARITY :none NUMBER-GF-DATA-BITS 8 

XGN-XGFF-PRGTGCGL yes 
User Property: DTR-UALID nil 

More information is available about editing the printer's namespace object. 
See the section "Attributes for Objects of Class "Printer"". See the section 
"Using the Namespace Editor". 

3. Set the baud rate to 9600 on the LGP2/LGP3 printer. 

Note: If you need more information about Macintosh serial ports, check the Unit 
specification conventions in the Maclvory User's Guide. 

For additional information about setting up the print spooler and the LGP2/LGP3 
printer,see the section "Installing a Printer". 

See the section "Uncrating the Printer". 

See the section "Specifying the Switch Settings". 

See the section "Loading the Hardcopy and Printer Support Tape". 

See the section "Registering a Printer". 

Note: If you boot the Maclvory while the print spooler is running, you must then 
restart the Macintosh computer. Otherwise, the serial stream is left open (and at- 
tempts to restart the print spooler will fail with an "unable to access the serial 
stream" error). 



Using an Appletalk Printer From the Macintosh and Genera 

• Printing via AppleTalk is supported only for Postscript printers. 

• Printing via AppleTalk can not be used with our Print Spooler. 
To use an AppleTalk printer do the following: 

1. Select your target printer on the Macintosh side through the Chooser. 
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2. Create a printer object in the namespace that identifies your Maclvory as the 
host to which the printer is connected. 

3. Set the default printer for your Maclvory to the printer object you just creat- 
ed. You can do this either in the namespace to make the effect permanent or 
with the Set Printer CP command. 

You can now use the printer from Lisp using the normal hardcopy facilities of 
Genera. 

The use of separate printer objects is required even if several Maclvories are us- 
ing the same AppleTalk printer. Of course, each printer object in the namespace 
must have a unique name and pretty name. Therefore it is a good idea to include 
the name of the Maclvory in the printer's names. 

For example, 

Showing PRINTER SOUR-CREAM-LOS-ANGELES-TIMES in namespace SCRC: 

Type: LGP2 

Site: SCRC 

Pretty Name: The Los Angeles Times for Sour Cream 

Interface: AppleTalk 

Host: SOUR-CREAM 

Printer Location: SCRC 2 Outside KMP's office 

The Type attribute should be LGP2, LGP3, or POSTSCRIPT depending on the type 
of printer. LGP2 corresponds to the old LaserWriter and LaserWriter Plus. LGP3 
corresponds to the newer LaserWriter IINT and LaserWriter IINTX. LGP3 also 
works for Apple's latest printer, the Personal LaserWriter NT. Use POSTSCRIPT 
for non-Apple Postscript printers (for example, HP). 

In the namespace object for the Maclvory, make sure that the BITMAP-PRINTER at- 
tribute is empty. Otherwise, Lisp tries to invoke the Print Spooler, which does not 
work. 

If your Macintosh is running MultiFinder, it's a good idea to enable background 
printing in the Chooser when you select your AppleTalk printer. Otherwise, when- 
ever you print something in Lisp, Genera stops while printing takes place. (You 
see the familiar Macintosh modal dialog boxes describing the print process appear 
in front of the Genera screen.) 



Setting the Size of Application Icons That Use Ivory 

If you use MultiFinder on the Macintosh, each application program icon has a 
memory size that you can control. Icons that give access to the Ivory coprocessor 
make extensive use of dynamic memory. Because their memory usage depends on 
your machine configuration, and because there is a tradeoff between memory con- 
sumption and performance, it can be to your advantage to adjust icon memory size 
to suit your particular needs. If you run Finder rather than MultiFinder on the 
Macintosh, application icons always use the full size of memory and you need not 
worry about this issue. 
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Icons that use the Macintosh window system, such as the Mac Dex example, can 
run in 256K and will run quite effectively in as little as 300K. Icons that use the 
Genera window system, such as the Genera icon, can run in 256K but will perform 
noticeably better with more memory. Genera uses large amounts of dynamic memo- 
ry for fonts, window bit arrays, and auto-load RPC servers. The recommended 
memory allocation for good performance is 250K plus four times the size of your 
screen, plus one more screen size if backup screens are enabled. You can deter- 
mine the size in K of your screen by evaluating this form: 

(values tv: (ceiling (* (sheet-width main-screen) (sheet-height main-screen) 
(screen-bits-per-pixel main-screen)) 
8192)) 

If you have plenty of memory on your Macintosh, you can set the size larger than 
this and get a small further improvement in performance, especially if you use a 
lot of large windows. If your Macintosh has a limited amount of memory or you 
want to save a lot of memory for running other applications at the same time as 
Genera, you can set the size of the Genera icon smaller, but switching windows 
will be slower. 

You can set the size of an icon with the Configure Maclvory Application command 
or by using the procedure described in Apple documentation for setting the size of 
an application. 



Configure Maclvory Application Command 

Configure Maclvory Application 

Use the Configure Maclvory Application command with no arguments. It presents 
a menu of fields which you must fill out and then press End. 

The menu presents these fields: 

From file An existing Ivory-using Macintosh application; you can use 

Genera. For example, if Genera is on the desktop you can use 
the file name HOST :dis^: Genera, where disk is the name of 
your Macintosh's hard disk. 

To file The name of a Macintosh file in which to place the output; it 

should have the same name as your define-remote-program- 
framework. 

Application The name of your define-remote-program-framework (use the 

pretty name). 

Version A Macintosh- style version number for your application, for in- 

stance l.OdO. 

Agent Leave this set to Emb (which means that the application ex- 

pects to find an embedded Ivory processor). 

Initial application command 

Set this to a command line that invokes a command defined by 
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your application that should be executed to start it up. Or you 
can leave this set to None, if the application should simply 
wait for a command (for example, from the menu bar) when 
started up. 

If the host has more than one monitor, you can specify the number of the monitor 
(display screen) that will be used by Genera, using the : screen-number argument. 
These are the same numbers displayed in the Monitors section of the Macintosh 
Control Panel. Specifying "default" means the main monitor, the one with the 
menu bar on it. This is the default if you do not specify this argument. 

If you leave the Initial application command field set to None, rather than supply- 
ing a Start Screen command, when Genera is started it will display a dialog box 
allowing interactive input of the arguments to the Start Screen command. The 
fields displayed in the dialog box depend on the hardware configuration, just like 
the command arguments noted above. 

The arguments accepted by the Start Screen command, after the first few, vary de- 
pending on the available hardware. If you wish to specify these arguments you 
should run the Configure Maclvory Application command on the same machine 
where you will run the resulting icon, or on a machine with a similar hardware 
configuration. 

If the host has color display hardware, you can specify whether the Genera window 
system should run in color mode or in monochrome mode, using the :multi-bit- 
screen argument; see the section "Basic Color Support in Maclvory". 



Controlling the Genera Screen on a Maclvory 



Controlling the Size and Placement of a Genera Screen on a Maclvory 

You can use Backup screens by using the Enable/Disable Backup screen option 
from the Macintosh Options menu. This option enables you to place one screen on 
top of another and to use each screen individually. 

You can use Movable screens by using the Enable/Disable Movable screen option 
from the Macintosh Options menu. This option enables you to adjust the size of 
the Genera screen in the same manner that you adjust the size of a Macintosh 
screen. 



Using the Maclvory Control Panel 

The Maclvory control panel lets you easily perform various maintenance functions 
for the Maclvory system. It is integrated as part of the Apple control panel. You 
can access the Macintosh control panel by clicking on Control Panel from the Ap- 
ple pull-down menu and then scrolling through the left-hand column to the 
Maclvory icon. 

The control panel's three window panes describe these areas: 
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• Hardware information 



• Status and configuration options 

• Disk maintenance and manipulation 

Figure ! displays the initial Maclvory control panel. 
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Figure 92. The Maclvory Control Panel 



Hardware status Describes the Ivory processor and the NuBus memory that it 
uses, if they are present. Memory size is specified both as raw 
size in megabytes (MB) and usable size in megawords (MW) of 
40 bits each plus 8 error correction bits. Additional hardware 
configuration details are available from Genera commands such 
as Show Herald and Show Machine Configuration. 

Status and configuration options 

The middle pane displays these command buttons: 

[Configure], which brings up a dialog that you can use to ex- 
amine and change several software configuration parameters. 
Most users will never need to change these parameters. The 

[Help] button in the dialog explains how to use it. Figure ! dis- 
plays this dialog. 

[Ethernet Grabbed], which is checked if an Ethernet interface 
exists and the Ivory is using it. If this box is not checked, the 
Macintosh can use the Ethernet interface if one exists. Click- 
ing on this box switches control of the Ethernet interface be- 
tween the Ivory and the Macintosh. This change takes effect 
immediately. 
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[Status], which brings up a scrollable window containing the 
current status of communications between the Ivory guest and 
the Macintosh host. Click on the window's close box to return 
to the control panel. 

[Help], which brings up a scrollable window containing help 
information. Click on the window's close box to return to the 
control panel. 



Configure Macluory Life Support 
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Figure 93. The Configure Maclvory Life Support Dialog 



Maclvory disk partitions 

Use this pane to examine and change the Maclvory disk parti- 
tions. The Maclvory control panel Help facility provides de- 
tailed information, including how to select, create, and delete a 
partition. 

You can access the Disk Copy/Compare utility from the [Copy] 
button in this window. This utility can copy one disk to anoth- 
er or compare two disks and report any differences. The utility 
operates on Maclvory disk partitions or on Macintosh disks. 

Initially, it is set for Maclvory disk partitions. Figure ! displays 
this dialog window. 

Click on the [Help] button for further information on how to 
use Disk Copy/Compare. 

See the section "Setting up a Disk for Use with Maclvory" for information on us- 
ing the control panel to create Ivory disk partitions. 



Using the Symbolics Keyboard with Native Macintosh Applications 
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Disk Copy/Compare Utility 
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Figure 94. The Maclvory Disk Copy/Compare Utility Dialog 



Use of the Symbolics keyboard with the Maclvory is provided primarily for compat- 
ibility with Genera applications. In addition, Symbolics supports the use of the 
Symbolics keyboard with native Macintosh applications. 



Mapping of Apple Key Functions to the Symbolics Keyboard 

All "ordinary" characters (printing graphics, TRB^ SPRCE^ RETURN) work normal- 

ly. 

Apple's ESC key is entered using our ESCRPE key. 

Apple's COMMRND key is entered using either of our SUPER keys. 

Apple's OPTION key is entered using either of our METR keys. 

Apple's CONTROL key is entered using either of our CONTROL keys. 

Apple's ENTER key is entered using our SCROLL key. 

Apple's CLERR key is entered using our CLERR INPUT key. 

Apple's HELP key is entered using our HELP key. 

Apple's END key is entered using our END key. 

Function keys (Fl - F15) are entered using the FUNCTION key as a shift key as 
follows: 
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The numeric keypad keys are entered using the SYMBOL key as a shift key as 
follows: 
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Note: In the table above, no mappings are provided for numeric 8^ numeric =, 
numeric *, and numeric +. These four characters require special treatment be- 
cause * is SHIFT 8 and + is SHIFT =. Symbolics distinguishes NUMERIC SHIFT 8 
from NUMERIC * by enabling you to use the SHIFT key on the same side as the 
SYMBOL for producing the unshifted key with a SHIFT modifier, and using the 
SHIFT and SYMBOL keys on opposite sides for producing the shifted key without a 
modifier. Note that both SHIFT keys are required to produce a shifted key with a 
SHIFT modifier. For example: 

LEFT SYMBOL 8 produces NUMERIC 8 

LEFT SYMBOL LEFT SHIFT 8 produces NUMERIC SHIFT 8 

LEFT SYMBOL RIGHT SHIFT 8 produces NUMERIC * 

LEFT SYMBOL LEFT SHIFT RIGHT SHIFT 8 produces NUMERIC SHIFT * 

LEFT SYMBOL = produces NUMERIC = 

LEFT SYMBOL LEFT SHIFT = produces NUMERIC SHIFT = 

LEFT SYMBOL RIGHT SHIFT = produces NUMERIC + 

LEFT SYMBOL LEFT SHIFT RIGHT SHIFT = produces NUMERIC SHIFT + 

The remaining keys on the extended keyboard are entered using the SYMBOL key as 
a shift key as follows: 
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Interoperability of the Symbolics Keyboard and Popular Macintosh Software 

Certain popular Macintosh software does not interoperate fully with the Symbolics 
keyboard. In some cases, a simple workaround (for example, renaming a file) exists 
which enables full function. In other cases, there is no workaround but the limita- 
tions are well known and are presented here for your convenience. 

The Symbolics Keyboard and CloseView 

CloseView, from Apple, allows the visually handicapped to magnify portions of 
their screen to make reading the screen easier. When using a Symbolics keyboard, 
however, the keystrokes used to raise and lower the magnification factor, Com- 
mand-Option-t and Command-Option-l, respectively, can not be entered using the 
techniques described in "Mapping of Apple Key Functions to the Symbolics Key- 
board". Instead, you must disable magnification using Command-Option-X, open the 
CloseView control panel, change the magnification factor by clicking on the arrow 
buttons, close the CloseView control panel, and re-enable magnification using Com- 
mand-Option-X. 

The Symbolics Keyboard and Pyro! 

Pyro!, from Fifth Generation Systems, is one of the most popular screen saver fa- 
cilities for the Macintosh. Once running, Pyro! waits for you to press any key or 
move the mouse as an indication that you wish to restore the normal screen con- 
tents. However, when using a Symbolics keyboard, Pyro! will not deactivate itself if 
you press any of the righthand modifier keys (that is, SHIFT, CONTROL, METR, and 
SUPER). Just use the lefhand modifier keys instead and Pyro! will deactivate. 

The Symbolics Keyboard and QuickKeys 2 

QuickKeys 2, from CE Software, is one of the most popular keyboard macro facili- 
ties for the Macintosh. For proper operation, the Symbolics keyboard software must 
load after Maclvory's support software but before QuickKeys 2. If you have INIT- 
Picker, or similar software for controlling the order in which INITs are loaded, see 
the documentation on said software for details on how to arrange the proper load- 
ing order. If you do not have such software, you can use the fact that the Macin- 
tosh System Software loads INITs in alphabetical order to get the desired effect. 
In particular, you can rename either the Symbolics Keyboard INIT or the Quick- 
Keys 2 INIT to obtain the proper loading order. (We recommend that you rename 
Symbolics Keyboard to MSymbolics Keyboard.) 



Known Keyboard Problems in Using the Genera Application with Maclvory 

This section describes some keyboard problems that occur with both the Symbolics 
keyboard and the Apple extended keyboard when using the Genera application. 

• The software flag that enables the posting of key up events to the application 
was not designed with MultiFinder in mind. 
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If the ADB bus interrupt for the button release goes off while another applica- 
tion or part of the system is running, no key up event is posted to the applica- 
tion that requested them. Apple has acknowledged this problem in a recent tech- 
nical memorandum. Genera tries to work around this by polling the system's in- 
ternal keys state looking for lost transitions. This polling results in some small 
performance degradation, but is mostly effective. Synchronization anomalies are 
rare but still possible. 

The event queue is very small. 

If the Macintosh is very busy processing high-priority disk interrupts, it may not 
run the application often enough to read out pending keyboard events and pass 
them on to the Ivory. If keyboard hardware interrupts occur while the event 
queue is full, the transitions are lost. Since the Macintosh does not normally op- 
erate the disk and network as hard asynchronously, and many applications do 
not support typeahead consistently, this is not a major problem for native appli- 
cations. In any case, typeahead is not as reliable on the Maclvory as on other 
Symbolics machines. 

The size of the event queue is determined by a field in the disk's boot block. 
Apple does not distribute an application for modifying this. Additionally, it has 
forbidden the distribution of licensed application software that does so. 



Configuring the Logitech MouseMan for Use with a Maclvory 

You must be running Maclvory Support Software Version 4.2 to use the Logitech 
MouseMan with Maclvory. These instructions presume that you have already in- 
stalled the MouseMan and its software according to Logitech's documentation. 

1. Open the Mouse Key control panel. 

2. Click on the Add button and select your copy of the Genera application. 

3. Change the assignments for the middle and right mouse buttons to be Click. 
Repeat steps 2 and 3 for the Unassigned application as well. 

4. Close the Control Panel. 

You can now use all three buttons on the MouseMan just as you would use the 
buttons on a Symbolics mouse while in Genera. The MouseMan will continue to 
behave according to your previous configuration instructions outside the Genera 
application. 

Running Two Genera Releases on a Single Maclvory 
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It is possible, although tricky, to allow two different major releases to coexist on 
the same Maclvory system. This section describes how to prepare for running two 
Genera releases (what you need to keep, and how to organize the files), and how 
to switch from one release to the other. 

For the purpose of a specific example, we assume you are running the Genera 7.4 
and Genera 8.1 releases. 

Preparation for Running Two Genera Reieases 

For each Genera release, you need to keep the Genera world, the corresponding 
FEP (kernel and flod files), and all Macintosh software (the three folders: 
Maclvory Applications, Maclvory System, and Maclvory Development). 

For safety's sake, you should keep the floppies or CD-ROM distributed from Sym- 
bolics in a safe place, in case any of these files are deleted accidentally. 

You should rename the folders so that they clearly represent the software in them: 

• The Genera 7.4 versions of the folders should be named: 7.4 Maclvory Applica- 
tions, 7.4 Maclvory System, and 7.4 Maclvory Development. 

• The Genera 8.1 versions of the folders should be named: 8.1 Maclvory Applica- 
tions, 8.1 Maclvory System, and 8.1 Maclvory Development. 

You need to have three sets of hello.boot and boot.boot files, one for Genera 7.4, 
one for Genera 8.1, and one to identify which release to run: 

• The 7-4-HELLO.BOOT file should load the FEP version for Genera 7.4. The 7-4- 
BOOT.BOOT file should load the Genera 7.4 world. 

• The 8-1 -HELLO.BOOT file should load the FEP version for Genera 8.1. The 8-1- 
BOOT.BOOT file should load the Genera 8.1 world. 

• The HELLO.BOOT file should contain "Hello 8-1" or "Hello 7-4"; this indicates 
which of the two above hello.boot files to use. The boot.boot file should con- 
tain "Boot 8-1" or "Boot 7-4"; this indicates which of the two above boot.boot 
files to use. 

Switching From One Genera Reiease to the Other 

Assume you are running Genera 8.1 and want to switch to running Genera 7.4. 
Follow these steps: 

1. Before shutting down Genera 8.1, edit the hello.boot file to contain "Hello 
7-4". Edit the boot.boot file to contain "Boot 7-4". 

2. Before shutting down Genera 8.1, you need to switch FEP kernels. When you 
are running Genera 8.1, you can do this by using the Edit Disk Label com- 
mand. When switching from Genera 8.1 to Genera 7.4, you would indicate the 
1311 FEP (which was the 7.4 FEP). 
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Note, however, when you are running Genera 7.4, the Edit Disk Label com- 
mand is not defined. Thus, to switch from Genera 7.4 to Genera 8.1, you need 
to use si:install-fep-kernel. For example, to switch to the 1325 FEP which is 
the 8.1 FEP, you would evaluate the following form: 

(si : instal l-fep-kernel " 1325-kernel ") 

3. Shutdown Lisp, by choosing "Shut Down" from the Ivory pulldown menu. This 
quits the Genera application. 

4. Copy the contents of the 7.4 Maclvory System folder to the System folder. Be 
sure to hold down the Option key while dragging to copy, not move the 
contents of the folder; you should always keep the contents of the 7.4 
Maclvory System folder so you can copy it again later. The system asks if you 
want to replace the files with the same names; you should answer Yes. 

5. Restart the Macintosh. 

6. When the Macintosh is running again, open the 7.4 Maclvory Applications 
folder and run the Genera application. If you are asked whether you want to 
cold boot, answer Yes. (If you are not asked, then the system cold booted au- 
tomatically.) 

To switch from Genera 7.4 to Genera 8.1, use the same process, but switch "8-1" 
and "7-4". 



Programmer's Reference to Maclvory 



Remote Procedure Call for the Macintosh 

This section presents information on using the Symbolics implementation of Re- 
mote Procedure Call (RPC) with Maclvory applications. It includes an overview of 
Symbolics RPC and a description RPC facilities specific to the Maclvory. 



Overview of Symbolics RPC 

Symbolics RPC is an implementation of industry-standard RPC that underlies Sun 
Microsystems' NFS and other programs (see Request for Comments (RFC) #1057 
"RPC: Remote Procedure Call Protocol specification version 2"). The distinguishing 
characteristic of Symbolics RPC is that it uses Lisp technology to provide a very 
clean and easy-to-use interface for defining RPC-based programs. The form of data 
transmitted over the communications medium is fully compliant with the standard. 

Remote Procedure Call (RPC) is a facility that allows a function executing on one 
processor to call a function executing on another processor. The two functions can 
be written in the same language or in different languages, such as Lisp and C. 
The two processors can be of the same type or of different types; for example, a 
function executing on an Ivory can call a function that executes on an MC68020. 
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RFC allows a program executing on one processor to access facilities that are 
available on another processor. For example, an Ivory embedded in a host can use 
RFC to make use of hardware devices controlled by that host, to call facilities of 
the host operating system, and to call program libraries that are available for the 
host but not for the Ivory. Similarly, a program running on a host can use RFC to 
call symbolic processing facilities such as Joshua that run on the Ivory. 

Using RFC, you can segment a program into pieces and run each piece on a differ- 
ent processor. This can improve performance through parallel processing. More 
importantly, this allows each part of the program to execute on the processor and 
under the operating system best adapted to support that part. Benefits include 
both performance improvement and ease of programming. 

For example, a program for a Maclvory system can run its user interface on the 
Macintosh and its knowledge processing on the Ivory. It is not necessary to have 
such a large granularity in the segmentation of a program; the same program 
might be improved by running the high-level "policy" portion of its user interface 
on the Ivory, with the low-level "mechanism" portion running on the Macintosh. 
Dynamic Windows on Maclvory work precisely this way. 

Another reason to use RFC is when you want to run a program on processor A but 
it needs to cooperate with an existing program that is available only on processor 
B. Frocessor A might be an Ivory, which you are using because of its ease of pro- 
gramming, while processor B might be a non-Symbolics processor, with a large li- 
brary of available programs. The main part of your program runs on processor A 
and it includes an appendage that runs on processor B; the appendage communi- 
cates with the existing program using the interfaces defined by the existing pro- 
gram. The main part of your program and the appendage communicate through 
RFC. The existing program is unaware of RFC and does not have to be modified 
or adapted. (The Genera interface to HyperCard on Maclvory works this way.) 

RFC provides communication between two processors in a single system, as when a 
Symbolics Ivory is embedded in a non-Symbolics platform such as a Macintosh or 
Sun. 

In this case communication is through shared memory and is quite efficient, al- 
though of course calling a function remotely is never as fast as calling it locally. 
RFC can also be used for communication between two processors in separate sys- 
tems, which might be physically located side by side or at a great distance from 
each other. RFC operates through local-area and wide-area networks and through 
RS232 serial lines. Using RFC over a network is slower than using RFC in an em- 
bedded system. 

Symbolics RFC provides a transparent interface; calling a function remotely looks 
the same as calling a local function. When you call a function, you do not have to 
know whether its body executes on the local processor or on a remote processor. 
This is true regardless of whether you program in Lisp or in C. The RFC system 
implements this by automatically defining a stub function that acts as a local rep- 
resentative of the remote function. The stub takes care of all the housekeeping re- 
quired to transmit the arguments to the remote function and receive back the val- 
ues. Symbolics RFC provides a transparent interface for the callee as well. You 
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write the body of a remotely callable function in Lisp or C in the usual way; the 
RFC system automatically adds code to receive the arguments, puts them in vari- 
ables with the names you specified, and sends back the results. 



Symbolics RPC and Sun RPC 

Symbolics RPC is a fully compliant implementation of the RPC and XDR (external 
Data Representation) standards described in RFC (Request for Comments) #1057 
"RPC: Remote Procedure Call Protocol specification version 2" and RFC #1014 
"XDR: External Data Representation standard." 

As such, it is completely compatible and can interoperate with any other compliant 
RPC implementation, such as the one supplied with Sun Microsystems computers. 
(See the Sun Microsystems document Network Programming for further informa- 
tion.) For instance, a program written in Symbolics RPC can make RPC calls to a 
program written in SunRPC language, and vice versa. 

Symbolics RPC language differs from SunRPC language in many ways, most no- 
tably in that Symbolics RPC can simultaneously generate code in two programming 
languages, C and Lisp. Symbolics RPC language cannot generate code in Sun RPC 
language. Users of the Symbolics UX can choose either for programming. Symbol- 
ics RPC language is likely to make the code-maintenance task easier for programs 
that will run on both Ivory-based systems and a C-based system. 



Differences Between Local and Remote Function Calling 

An important and necessary difference between local and remote function calling is 
that functions executing on separate processors have separate memory address 
spaces and cannot share any data. All arguments and values must be passed by 
value, not by reference. For this reason, unlike a locally callable function, a re- 
motely callable function uses special functions (rpcrrpc-values and rpc:rpc-error 
in Lisp, RPCValues and RPCError in C) to return its results. 

Because there is no call by reference, the data types that can be used with RPC 
are limited. For example, in Lisp you cannot pass an arbitrary symbol as an argu- 
ment. If you pass a flavor instance, the callee sees a copy of the instance. If the 
callee modifies the instance, those modifications are not passed back to the caller. 
On the other hand, a benefit of call by value is that the caller and callee can use 
different data representations. For example, the caller can pass a Lisp flavor in- 
stance, which the callee will see as a C struct. 

You construct an RPC-based program by using a set of Lisp macros to define the 
remotely callable functions. These Lisp macros are somewhat unusual in that they 
expand into both Lisp code and C code. The Lisp expansion is processed in the 
normal way. The C expansion is written to a file that can be compiled by the Sym- 
bolics C compiler or shipped to another processor and compiled by its own C com- 
piler. Once the interface has been defined and compiled, you call the stub func- 
tions using ordinary Lisp or C function calls. The callee or server half of the in- 
terface is loaded together with any other programs it calls. 
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Basic Concepts of RPC 

The basic concepts of RPC include remote modules, rem,ote entries, remote errors, 
and remote types, explained in the following table: 

remote entry A remotely callable function. 

remote module A collection of related remote entries that are treated as a unit 

for bookkeeping purposes. 

remote error An exceptional condition that can arise while executing a re- 

mote entry. 

remote type A type of data that can be used as an argument to a remote 

entry or a remote error, and can be returned as a value by a 
remote entry. A remote type defines the possible data values, 
their representation in Lisp and C, their representation for in- 
terprocessor transmission, and the methods for converting be- 
tween these representations. 

Some of these concepts have nonstandard names. These names were chosen to 
avoid any confusion with other concepts in Genera with names similar to the stan- 
dard names. Other systems call remote modules "remote programs" and call remote 
entries "remote procedures." 

The RPC facility consists of three layers: 

• The call layer is in charge of identifying remote entries to be called, transmit- 
ting the arguments to them, matching up the returned values with the caller 
who is awaiting the results, and reporting errors. 



• 



The data representation layer is in charge of defining a common representation 
for data and translating representations used by different machines and by dif- 
ferent programming languages to and from the common representation. 

The transport layer is in charge of moving raw bits between machines and deal- 
ing with bit-ordering issues. There are three different transport layers, se- 
lectable at run time. One is based on the embedding substrate's inter-processor 
communication mechanism, the others are based on the byte-stream and UDP/IP 
media of the generic network system. 



Types of RPC Servers for Maclvory 

The :type option to rpc:define-remote-c-program defines three types of servers: 
linked, auto-load, and auto-load-with-static-data. When choosing which type of serv- 
er to use, your first decision is whether to use a linked server or an auto-load 
server. A linked server is an integral part of an application program, built into 
that program and able to call subroutines of it and access its static data. An auto- 
load server is an independently created module that executes inside an application 
program without any knowledge of the structure of the application. 
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If you are not writing your own application program, your choice is simple, be- 
cause only auto-load servers are possible; to use a linked server you must have a 
program to link it into. If you are writing your own application program, whether 
to use a linked server or an auto-load server depends mainly on whether you want 
to maintain the server independently, or tie it closely to the application program. 

If you are running the Symbolics-supplied application program, such as the Genera 
icon or other icons that you created from the Symbolics-supplied Genera or Unas- 
signed icon using the Configure Maclvory Application command, you must use an 
auto-load server, since you cannot modify this program to link in your own servers. 
The same auto-load server can also be used with your own application programs. 
The Macintosh Toolbox interface is implemented entirely with auto-load servers so 
that it is available in all applications, including the ones you write yourself. 

On the Macintosh, an auto-load server only occupies memory if it is called, while a 
linked server may or may not occupy memory even if it is not called, depending on 
whether you direct the linker to put it in its own segment. 

If you choose an auto-load server, your next decision is whether to use :auto-load- 
with-static-data or plain :auto-load. In general, the :auto-load type is preferable 
because it allows you to set the "purgeable" bit in the resource, which in turn al- 
lows your server to be swapped out when it is not executing if the Macintosh gets 
low on memory. However, you must use :auto-load-with-static-data if you have 
static variables in your C code or use the :init option to rpc:define-remote-c- 
program. 

The "purgeable" bit in each RPCD resource controls memory allocation for that 
code segment. You can use the Attrs item in [Project / Set Project Type...] in 
THINK C to set this bit before compiling your program. If the "purgeable" bit is 
off, the code segment is loaded in to memory and locked when your remote module 
is first called and remains in memory at a fixed address forever (until the applica- 
tion quits). This is the normal setting. If the purgeable bit is on, the code segment 
can be moved to a different memory address, or unloaded from memory entirely, 
any time a call to it is not actively in progress. Set the purgeable bit if you want 
to minimize memory consumption, but only if your program does not use inter- 
rupts, VBL tasks, call backs, or anything else that could fail if the program's 
memory address changes. 

An auto-load server is always locked while it is executing. If you do not set the 
purgeable bit, it is locked at all times, but if you do set the purgeable bit, it is un- 
locked between calls. You should not set the resource's "locked" bit nor its 
"sysHeap" bit. The purgeable bit should not be used for :auto-load-with-static- 
data RPC servers. If you use it, the values of your static variables will be reset at 
unpredictable times. 

The Macintosh has certain limitations on code resources. Since auto-load and auto- 
load-with-static-data RPC servers are implemented as code resources, they are sub- 
ject to these limitations. The maximum size of a code resource is 32K bytes. If you 
exceed this limit you may be able to work around it by breaking up your 
rpcrdefine-remote-module into several separate modules. Code resources access 
their global variables through register A4 instead of the normal register A5. The 
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RFC system maintains these registers for you, but problems can still occur if you 
use libraries. You may need to copy and recompile any libraries that you use, as 
explained on page 85 of the THINK C manual. If you access certain QuickDraw 
globals such as the built-in cursor shapes and stipple patterns you will find that 
they don't work correctly. 

Auto-loading Servers for RPC 

This section tells you how to create an auto-loading RPC server. It provides a sam- 
ple remote program and a procedure for creating an auto-loading server. The serv- 
er is loaded into an RPC-bearing Macintosh application, such as "Genera", the first 
time the Ivory tries to call it. 

First, define your remote program. You can find the one used in this example, 
called remote-program-example. lisp in the file syS:EMBEDDING;RPC;EXAMPLES;REMOTE- 

PROGRAM-EXAMPLE.LISP. 

Remote Program Example 

; -*- Mode: LISP; Syntax: Lisp+C; Package: USER; Base: 10 -*- 

;> EXAMPLES-MESSAGE 

;> 

;> 

;> Symbolics hereby grants permission to customer to incorporate 
;> the examples in this file in any work belonging to customer. 
;> 

;;; A simple example of how to use RPC on Maclvory 

;;; This uses the Mac Standard File package to read a file name 

; This could be done through the toolbox interface, 

; but for purposes of this example, we are not 

; using the interface, instead doing the work by hand. 

;; Assign a number to the remote module and declare that it will 
;; be used for Lisp-to-C calls 

(RPC:DEFINE-REMOTE-MODULE EXAMPLE (: NUMBER ttx7F008000) (: VERSION 1) 

(:CLIENT :LISP) (:SER\/ER :C)) 

;;; Define the types that we will need 

;; Macintosh points. The Lisp representation is just (VECTOR \l H) . 
(RPC:DEFINE-REMOTE-TYPE POINT () 

(:ABBRE\/IATION-FOR ' (RPC : STRUCTURE (\l RPC : INTEGER-16) (H RPC : INTEGER-16) 

(:C tii Point })))) 
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; ; List of what file types we will accept, or wildcard that accepts all file types 
(RPC:DEFINE-REMOTE-TYPE FILE-TYPES () 

(:ABBRE\/IATION-FOR '(OR ALL (VECTOR FILE-TYPE)))) 

(RPC:DEFINE-REMOTE-TYPE ALL () 

(:ABBREUIATION-FOR '(MEMBER :ALL))) 

;; Macintosh file-type codes. The Lisp representation is a 4-character string. 
;; Since in C these are treated as long integers rather than arrays, we need 
;; to write some C code sending and receiving them instead of relying on 
;; the default action for vectors 
(RPC:DEFINE-REMOTE-TYPE FILE-TYPE () 

(:ABBREUIATION-FOR '(VECTOR RFC : CHARACTER-8 4)) 
(:C 

(: DECLARE (NAME) Ui OSType InAME }) 
(:SEND (VALUE) 
m send_word( iUALUE ); } 

) 
(:RECEIUE (VARIABLE STORAGE-MODE) 
(PROGN (IGNORE STORAGE-MODE) 

m iUARIABLE = receive_word(); } 
)))) 

Define the RFC interface to the Macintosh SFGetFile routine 
We tell it where to put the dialogue box on the screen and what 
file types we are interested in. It interacts with the user and returns 
whether the user confirmed or cancelled, the volume (really directory) 
identifying number, the file name, and the Macintosh file type code). 
(RPC:DEFINE-REMOTE-ENTRY READ-FILE-NAME EXAMPLE (: NUMBER 1) 

(: ARGUMENTS (WHERE POINT) 

(FILE-TYPES FILE-TYPES)) 
(: VALUES (CONFIRMED RFC: BOOLEAN) 
(VOLUME RPC:INTEGER-16) 
(FILE-NAME RPC : PASCAL-STRING) 
(FILE-TYPE FILE-TYPE)) 
;; Define the C glue code needed to interface to the operating system 
;; Put the list of file types into the form required by SFGetFile 
;; and extract the values from the SFReply structure 
(:C 

(: SERVER 
m SFReply reply; 
int numTypes; 
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if ( f ile_types. type == all_type ) 

numTypes = -1 ; 
else numTypes = file_types. value. vector->length; 
SFGetFile(where, "\p", NULL, numTypes, &file_types. value. vector->element[0] , 

NULL, &reply); 
RPC\/alues(reply .good, reply .vRefNum, reply. fName, reply . fType) ; 
»)) 

;; Output the C code to a separate file, for compilation on the Macintosh 
;; We only need server code 
(RPC:DEFINE-REMOTE-C-PROGRAM EXAMPLE 
(: SERVER 



( 
( 
( 

Notes: 



FILE "example. c") 

TYPE :AUTO-LOAD) 

INCLUDE "<MacTypes.h>" "<FileMgr .h>" "<StdFilePkg.h>"))) 



1. Note that Syntax in the attribute line is set to Lisp+C. This enables the #{...} 
syntax. 

2. 

In interprocessor communication, modules are identified by their number, not 
by name. Choose module numbers following the conventions in the file 
SYS:EMBEDDING;RPC;ASS1GNED-NUMBERS.TEXT . All module numbers for a particular 
site must be unique. 

3. You can replace the type :auto-load with :auto-load-with-static-data if you 
have static variables in your C code or use the :init option to rpcrdefine- 
remote-c-program. In general, the :auto-load type is preferable to :auto- 
load-with-static-data because it allows you to set the "purgeable" bit in the 
resource, which in turn allows your server to be swapped out if the Macintosh 
gets low on memory. 

4. The rinclude files are whatever include files your remote entries need. Here 
we need general Macintosh types such as Point, the Macintosh File Manager, 
and the Standard File package. 

Prerequisites 

Before beginning this procedure: 

• You must have THINK C loaded on your Macintosh disk. 

• From the Macintosh Finder, create a folder called RPC-Example on your Macin- 
tosh disk. This folder should not be in any other folder. 
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The procedure is divided into these steps: 

1. Compiling the example program in Genera 

2. Copying the C program to the Macintosh 

3. Compiling and linking the C program on the Macintosh 

4. Installing the code resource file 

5. Calling the remote module 
Procedure 

1. Compile the example program in Genera. 

a. Switch to Genera by double-clicking on the Genera application icon. 

b. Compile and load the example program from the Lisp Listener with the 
Compile File and Load File commands. 

This tells Genera about the remote module, and produces a C program in the 
file SYS:EMBEDDiNG;RPC;EXAMPLES;EXAMPLE.c Specified in rpc:define-remote-c- 
program (line 77). 

The next step is to use the example. c file to tell the Macintosh about the re- 
mote module. 

2. Copy the C program to the Macintosh. 

Use the Copy File command to copy the C program example. c from Genera to 
the RPC-Example folder on the Macintosh. 

For example, 

Copy File sysiembedding; rpc; examples; example. c HOST :dis^: RPC-Example: example. c 

In this example, HOST is used literally to specify the local Macintosh, disk is 
the name of that Macintosh's hard disk (the name displayed under the disk 
icon), and RPC-Example is the name of the folder. Note: If the disk has a 
space in its name, you must enclose the entire pathname in double quotes. 

3. Compile and link the C program on the Macintosh. 

This step describes the work necessary to compile and link the C program on 
the Macintosh. It tells you how to set up a THINK C project and how to com- 
pile and link your C program with it. See THINK C documentation for fur- 
ther information. 
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Before compiling the C program, create a file named RPC.h and a file named 
Maclvory-Suypport.h in the RPC-Example folder. The file should contain a 
Mnclude of the right file name (for example, "::MacIvory Devel- 
opment:RPC:RPC.h"). Follow these steps for this example: 

a. From Genera, type: 

Edit File HOST : disk: RPC-Example : rpc.h 

b. This places you at an editor window. Type in the following text: 
^include "::MacIvory Development:RPC: RPC.h" 

c. Save the buffer by typing c-H c-S. 

d. Follow a similar procedure to create a file named Maclvory-Support.h. 
Type the following text in the file: 

#include " : iMacIvory Development: Substrate: Maclvory-Support.h" 

The next task is to compile your C program and link it with the libraries or 
other C source files called by the C code in the rserver clauses of your 
rpcrdefine-remote-entry forms. In this example, we use the THINK C com- 
piler. If you are unfamiliar with this product, read the THINK C manual for 
background. 

This example uses one library, one source file from the RPC system, and no 
additional source files. (Note: For large C programs, which are not just calls 
to the Macintosh operating system, you might put the bulk of it in a separate 
file and put function calls in the rpcrdefine-remote-entry forms. This makes 
editing easier because you can edit the C code in C mode instead of Lisp 
mode.) 

a. Switch from Genera to the Macintosh Finder and start up THINK C. 
You are presented with a THINK C file selection box. 

b. From this box, move to the RPC-Example folder on the disk, (see "Start- 
ing THINK C" in the THINK C manual). To do this: 

i. Click on the THINK C open folder icon and move to disk, where 
disk is the name of your disk. 

ii. From the directory list of the contents of your disk, double-click on 
RPC-Example to open it. 

c. Create a THINK C project called example proj in the RPC-Example fold- 
er 
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The THINK C compiler has a number of options. This example assumes 
a particular setting of these options, which is normally the default, un- 
less the default has been changed at a particular installation. 

In [Edit / Options...], there are 5 sub-menus selected by radio buttons, of 
which we care only about two. In Code Generation, Macsbug Symbols 
and <MacHeaders> are assumed to be on, and the others are assumed to 
be off. In Compiler Flags, Check Pointer Types is assumed to be on, and 
Require Prototypes must be off. 

After setting the options, if necessary, create a project with these steps: 
i. Click on New in the file selection box. 

ii. At the prompt. Name New Project, type: example proj. 

d. Using [Source / Add ...] while still running THINK C, add the following 
three files to example proj: 

(Continue to work from the file selection box as described in the previ- 
ous step.) 

• Add the example. c file from the RPC-example folder on the disk. 

• Add the file rpcspprt.c in the RPC folder in the Maclvory Development 
folder. 

• Add the MacTraps library in the Mac Libraries folder in the THINK 
C folder. 

e. Click Cancel after adding those three files, to get out of the file menu. 

Set the project type and related information. Select [Project / Set Project 
Type] from the pull-down menu and set the radio button to Code Re- 
source. Specify the type (in the box) as RPCD (you must use all caps), 
the ID as 1, and the name to whatever you want (leaving it blank is 
okay). Be sure to type RPCD in all capital letters. Click OK and then OK 
again. This procedure tells THINK C to build a code resource file. 

Note: The "purgeable" bit in each RPCD resource controls memory allo- 
cation for that code segment. You can use the Attrs item in [Project / 
Set Project Type...] in THINK C to set this bit before compiling your 
program. If the "purgeable" bit is off, the code segment is loaded in to 
memory and locked when your remote module is first called and remains 
in memory at a fixed address forever (until the application quits). This is 
the normal setting. If the "purgeable" bit is on, the code segment can be 
moved to a different memory address, or unloaded from memory entirely, 
any time a call to it is not actively in progress. Set the "purgeable" bit if 
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you want to minimize memory consumption, but only if your program 
does not use interrupts, VBL tasks, call backs, or anything else that 
could fail if the program's memory address changes. 

f. Use [Project / Build Code Resource] to compile, link, and produce the 
output, with whatever name you want. 

g. The same name as in rpcrdefine-remote-module is customary, so for 
this example you put the output in a Macintosh file named example in 
the RPC-Example folder. Note: You will be in Mac Libraries and need to 
switch to RPC-example folder. Now you can use [File / Quit] to leave 
THINK C. 

Install the code resource file. 

The next step is to make the RPC system aware of the code resource file you 
just built. You need to do two Macintosh-oriented things: 

• Set the file's type and creator attributes to RPCS and IVRY instead of the 
default. 

• Create a resource of type RPCS with ID 1 (same ID as your RPCD re- 
source). 

This resource should be 8 bytes long, where the first 4 bytes are the 
rnumber option from rpcrdefine-remote-module and the second 4 bytes are 
the rversion option. Remember about decimal versus hexadecimal. 

If you know how to use ResEdit, you can do these operations graphically in 
ResEdit. Alternatively, you can do them textually in RMaker as described in 
the following procedure. 

a. Use the Genera command Copy File to copy the file 
SYS:EMBEDDING;RPC;EXAMPLES;EXAMPLE.R into the RPC-Example folder. Type: 

Copy File sysiembedding; rpc; examples; example. r Host:Disk:RPC-Example:example. r 

(Caution: RMaker requires that the text in this file appear exactly as 
given, including spaces and blank lines. This includes the blank line that 
ends the file.) 

b. Run RMaker and select the example. r file from the file menu. (You can 
use the Find File desk accessory, if you need help in finding RMaker.) 
When it finishes, click on the Quit button. You now have an Example 
Server file. 

c. Move this file into a folder where the RPC system can find it, which can 
be the folder where "Genera" is launched from, or the folder Disk-.System 
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Folder: Ivory:RPC: (the latter is preferable, since it keeps RFC servers 
separate from everything else). 

Now calling the remote module from Genera should work. 

5. Call the remote module. 

To call the example module, switch back into Genera and evaluate the form: 

(read-file-name #(150 100) :all) 

A standard Macintosh file menu appears near the middle of the screen. First 
try clicking the Cancel button. You get back values of NIL and three garbage 
values. Try it again and select a file, and you will get T, a negative number 
that encodes what folder the file is in, the name of the file as a string, and 
the Macintosh type of the file as another string. 

Incorporating RPC Into Macintosh Applications 

Symbolics provides a THINK C version 4.0 library named RFC. lib that implements 
the Remote Frocedure Call protocol between the host Macintosh and its embedded 
Ivory. The Genera application provided by Symbolics uses this library. 

You can link the RFC library into your own Macintosh applications. This allows 
you to use RFC to request services from the Ivory in your application by linking in 
stub files written by the rclient option of rpc:define-remote-c-program. 

In addition, the RFC library makes your application an RFC server for requests 
from the Ivory. The RFC library transparently provides all the support for auto- 
load RFC servers (see the section "Auto-loading Servers for RFC" for further in- 
formation). You can also link RFC server files written by the rserver option of 
rpc:define-remote-c-program into your application. Frograms running on Ivory 
can then call those servers. 

In order to use the RFC. lib library, you must also link in the Maclvory library pro- 
vided by Symbolics. 

The Maclvory library provides facilities for booting the Ivory, displaying the cold 
load stream, and related tasks. For an example of the use of these facilities, see 
the example program in the file syS:EMBEDDING;RPC;EXAMPLES;APPLICATION-example.c. 

The RFC library is available on the Macintosh in the file dis^:MacIvory 
Development:Libraries:RFC.lib, where disk is the name of your Macintosh's hard 
disk. The Maclvory library is available on the Macintosh in the file dis^:MacIvory 
Development:Libraries:MacIvory.lib, where disk is the name of your Macintosh's 
hard disk. 

In addition to these libraries. Symbolics also supplies the libraries RFC A4.1ib and 
Maclvory A4.1ib. These are identical to the Maclvory and RFC libraries except that 
they have been compiled to use register A4 instead of A5. Use these libraries 
when you are building code resources rather than applications. (See the section 
"Using libraries in code resources" in the THINK C User's Manual for further 
information.) 
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Your Macintosh application must be written in THINK C in order to use the RPC 
library. 



Initializing the RPC and Maclvory Libraries 

Your Macintosh application must initialize the RPC and Maclvory libraries before 
using them. Follow these steps to initialize the libraries: 

1. Initialize the Macintosh operating system and any other facilities you use. 

2. Call the functions InitMacIvorySupport and InitMacIvory. 

3. Call the function Initial izeRPC with no arguments. It does not return any- 
thing. 

4. Call initiaMze_remote_module_name_seryer with no arguments, for every 
RPC server file that you have linked into your application. You must always 
call initial ize_predefined_remote_entries_server, since that RPC server is 
included in the RPC library. These functions return a standard Macintosh er- 
ror code of type OSErr; however, it is generally safe to assume that no error 
occurred. 

5. Call the function emb_agent_open with no arguments. It returns a standard 
Macintosh error code and establishes a bidirectional channel between the host 
Macintosh and the embedded guest Ivory. If the value is not noErr, you 
should terminate the application. It is important to check this error code. If 
emb_agent_open fails, call the ReportRPCOpenFailure routine to issue a standard 
Macintosh alert box. 



Terminating the RPC and Maclvory Libraries 

Your Macintosh application must terminate the RPC and Maclvory libraries before 
it exits. Follow these steps: 

1. Optionally, call OKtoStopMac Ivory. (Use this to issue the standard "Lisp is 
running. Quit?" alert box). This function returns a value of TRUE or FALSE. 

2. Call the function CloseRPC with no arguments. This function does not return 
anything. If you exit without calling CloseRPC, the interprocessor communica- 
tion channel allocated by emb_agent_open remains permanently busy. 

3. Call TermMacIvorySupport. 

4. Call the function ExitToShell. 

Note: You must provide a function, ExitMacIvoryAppl i cation, which is called by 
the Maclvory library if it decides it is impossible to continue. This function must 
perform the last three actions above. Therefore, it is possible to replace steps 2 
through 4 with a call to your ExitMacIvoryAppl ication function. 
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Interfacing the RPC and Maclvory Libraries to an Event Loop 

The RPC hbrary interfaces with your apphcation's event processing loop in two 
directions: you call it, and it calls you. You must call the RPC library periodically, 
so that incoming requests from the Ivory can be serviced. Normally, this is done 
from your event processing loop. Even if you do not plan to make any RPC calls 
from Ivory to Macintosh, you still must call the RPC library to support internal 
housekeeping. 

The RPC library calls back to your event processing loop whenever it has to wait 
for some event to occur, normally a response from the Ivory. This happens when 
you make an RPC call from Macintosh to Ivory, for example. While the Macintosh 
waits for the Ivory to complete the call and return the values, the RPC library re- 
peatedly calls your event loop. 

Your event processing loop should call the function Pol 1 RPC with no arguments. It 
does not return any result. Call Poll RPC before calling WaitNextEvent or GetNex- 
tEvent or in the same circumstances in which you call SystemTask. 

MacIvoryTasks must be called periodically, typically from your application's main 
event loop. It handles reset requests from Ivory and maintains the cold-load-stream 
window. Like Poll RPC, MacIvoryTasks should be called before a call to WaitNex- 
tEvent or GetNextEvent, or in the same circumstances in which you call SystemTask. 

Your application's event processing loop should call MacIvoryEvent on every event, 
before processing it. MacIvoryEvent takes care of the Ivory menu and the cold-load- 
stream window. 

Your application must define the function BusyWait, to be called by the RPC library 
when it needs to wait. BusyWait takes one argument, an int named allow_rpc, and 
returns no values, al 1 ow_rpc is true if the RPC system expects you to call it back, 
or false if it does not. BusyWait should call MacIvoryTasks. You should call Poll RPC 
if and only if al 1 ow_rpc is true. 

BusyWait gives you an opportunity to implement whatever multiprocessing strategy 
you prefer. When using MultiFinder, BusyWait must call GetNextEvent or WaitNex- 
tEvent so that other Macintosh applications can run. In general it's a good idea for 
BusyWait to support the mouse at least to the extent of allowing the Apple menu to 
be used, but it is not a good idea for BusyWait to run portions of your application 
that can make RPC calls to the Ivory. 

You must define a routine named RestartMacIvoryAppl i cation, which is called with 
no arguments from Mac Ivory Tasks when the Ivory system is booted or restarted. 
RestartMacIvoryAppl i cation should reset whatever is appropriate to reset in your 
application. You must call CloseRPC in this function and then open a new channel. 

You must define ExitMacIvoryAppl i cation. This routine, which takes no arguments, 
cleans up after your application, calling CloseRPC, TermMacIvorySupport and Exit- 
ToShell. 

You must define a function NoteMacIvoryStateChange. It is called by the library 
whenever Ivory's state changes (that is, starts up, shuts down and so on). 
NoteMacIvoryStateChange is called with one agrument of the type enum MacIvoryS- 
tateTransisition, which indicates what just happened to the Ivory. 
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Using RPC in a Maclvory Application 

Once the RPC library has been initialized, you can make RPC calls to Ivory simply 
by calling the function. The rclient option of rpc:define-remote-c-program creates 
a file with the necessary "stub" code that does the interprocessor communication. 
Link this file into your application and RPC calls look like ordinary C function 
calls. All RPC calls return a standard Macintosh error code, which should be 
checked by the caller. If the RPC call has values, you pass extra arguments which 
are the addresses of the variables to receive the values. 

Because your application includes the RPC library, your application automatically 
supports dynamic loading of RPC servers defined with the (:type :auto-load) sub- 
option of the rserver option to rpc:define-remote-c-program. You can also link 
RPC servers directly into your program, which is useful when the servers share 
data or subroutines with the rest of your application. Use the (:type rlinked) sub- 
option of the rserver option to rpc:define-remote-c-program, and remember to call 
initialize_reinote_inodule_naine_server. 

If you issue several asynchronous RPC calls in rapid succession, you can't rely on 
the Ivory executing these calls in the order in which they were issued. In general 
the Ivory will execute all of the calls in parallel, each in a separate process. (Note: 
an asynchronous call is a call to an entry whose rpcrdefine-remote-entry form us- 
es the rasynchronous option.) 

If you depend on asynchronous RPC calls to be executed one at a time in order, 
you should use the (rprocess nil) option of rpcrdefine-remote-module. This causes 
all calls to entries in that module to be executed in the RPC Dispatch process, 
rather than in separate processes, which means that each call will be fully pro- 
cessed before handling of the next call commences. This feature should be used 
with caution, because if your server doesn't return, the RPC Dispatch process will 
be out of operation and the Ivory will appear to be dead and non-responsive. 

Note that if some entries of a particular remote module should be executed in the 
RPC Dispatch process while other entries should be executed in separate processes, 
you should either put the latter entries into a separate remote module or call 
process-run-function explicitly in your server code. 



Selecting the Right RPC Agent for Maclvory Applications 

When multiple Macintosh applications are using the Ivory simultaneously, software 
that runs on the Ivory needs to know which Macintosh application it is talking to 
in order to perform RPC calls and have them served in the right context. If you 
only make Macintosh-to-Ivory calls, and not the reverse, you don't need to worry 
about this. 

When a Lisp program makes an RPC call, it is actually calling a "stub" function 
that does the interprocessor communication. This stub uses the special variable 
rpc:*default-transport-agent* to tell it what server to communicate with. The 
global value of rpc:*default-transport-agent* refers to a Macintosh application 
such as Genera, or one created with the Configure Maclvory Application command, 
that provides the full range of services. When your application makes a Macintosh- 
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to-Ivory call, rpc:*default-transport-agent* is bound in the Ivory process that exe- 
cutes the server to the agent that connects to your application. Thus if in the pro- 
cess of serving a call from the Macintosh the Ivory calls back to the Macintosh, it 
will reach the right application. 

If the Ivory side of your application uses multiple processes, you will need to pay 
special attention to rpc:*default-transport-agent*. Otherwise, it is likely to have 
the desired value automatically. 



Example of a Simple Macintosh Application 

This procedure goes through the steps of building a simple example application 
that runs on the Macintosh and uses RPC to obtain services from the Ivory copro- 
cessor. The example service we use is to retrieve the property list of a symbol and 
display it in a Macintosh window. The Plist command in the File menu does this. 
The usual Macintosh window manipulation commands are also provided. The 
source code for this example is contained in the following files: 

SYS:EMBEDDING;RPC;EXAMPLES;PLIST-SERVER.LISP 
SYS:EMBEDDING;RPC;EXAMPLES;APPLICAT10N-EXAMPLE.C 

Prerequisites 

Before beginning this procedure: 

• You must have THINK C loaded on your Macintosh disk. 

• From the Macintosh Finder, create a folder called RPC-Example on your Macin- 
tosh disk. This folder should not be in any other folder. 

The procedure is divided into these steps: 

• Compiling the server side of the program 

• Copying the client side of the example program to the Macintosh 

• Compiling the client side of the program 

• Compiling and linking the C program on the Macintosh 

• Running the program 
Procedure 

1. Compile the server side of the example program. 

a. Switch to Genera by double-clicking on the Genera application icon. 
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b. Compile and load the example server program from the Lisp Listener 
with the Compile File and Load File commands, operating on the file 

SYS:EMBEDDING;RPC;EXAMPLES;PLIST-SERVER.LISP. 

This tells Genera about the remote module, and produces a C program in the 
file SYS:EMBEDDiNG;RPC;EXAMPLES;PLiST-SERVER.c Specified in rpc:define-remote-c- 
program. 

2. Copy the client side of the example program to the Macintosh 

Copy the C source code to the Macintosh. Use the Copy File command to copy 
the stubs for the example server program to the RPC-Example folder on the 
Macintosh, and to copy the source code for the Macintosh application to the 
same folder. 

For example. 

Copy File sysiembedding; rpc;examples;pl ist-server.c HOST : disk: RPC-Example: 

Copy File sys:embedding; rpc;examples;appl ication-example.c HOST : disk: RPC-Example: 

In this example, HOST is used literally to specify the local Macintosh, disk is 
the name of that Macintosh's hard disk (the name displayed under the disk 
icon), and RPC-Exampl e is the name of the folder. 

3. Compile and link the C program on the Macintosh. 

Before compiling the C program, create files named RPC.h and Maclvory- 
Support.h in the RPC-Example folder. These files should contain a ^include of 
the appropriate file names. 

Follow these steps for this example: 

a. From Genera, type: 

Edit File HOST : disk: RPC-Exampl e: rpc.h 

b. This places you in an editor window. Type in the following text: 

^include "::MacIvory Development: RFC: RPC.h" 

c. Save the buffer by typing c-H c-S. 

d. Type c-H c-F. When asked for a file name, type: 

HOST : di sk : RPC-Exampl e : Mac I vory-Support . h 

e. Type in the following text: 
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^include " : :MacIvory Development: Substrate: Mad vory-Support.h" 

f. Save the buffer by typing c-H c-S. 

The next task is to compile your C program and link it with the necessary li- 
braries. In this example, we use the THINK C compiler. If you are unfamiliar 
with this product, read over the THINK C manual for background. 

This example uses the two source files we just copied onto the Macintosh and 
four libraries. 

a. Switch from Genera to the Macintosh Finder and open the disk if it's 
not already open. 

b. Double-chck on the THINK C Folder to open it. 

c. Double-chck on the THINK C icon in the THINK C folder to start up 
THINK C. You are presented with a THINK C file selection box. 

d. From this box, move to the RPC-Example folder on the disk. (See "Start- 
ing THINK C" in the THINK C manual). To do this: 

i. Click on the THINK C open folder icon and move to DSK (your 
disk). 

ii. In the directory list of the contents of DSK (your disk), double-click 
on RPC-Example so that it is opened. 

e. Create a THINK C project called Application-example proj in the RPC- 
Example folder. 

The THINK C compiler has a number of options. This example assumes 
a particular setting of these options, which is normally the default, un- 
less the default has been changed at a particular installation. 

In [Edit / Options...], there are five sub-menus selected by radio buttons, 
of which we only care about two. In Code Generation, Macsbug Symbols 
and <MacHeaders> are assumed to be on, the others are assumed to be 
off. In Compiler Flags, Check Pointer Types is assumed to be on. Re- 
quire Prototypes must be off. 

In [Project / Set Project Type...], File Type is APPL, Creator is ????, Sep- 
arate STRs is checked, and MF Attrs is 0000. 

After setting the options, if necessary, create a project with these steps: 
i. Click on New in the file selection box. 
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ii. At the prompt, Name New Project, type: Application-example proj. 

f. Using [Source / Add ...] while still running THINK C, add the following 
files to Application-example proj (continue to work from the file selection 
box as described in the previous step): 

• Add the application-example. c file from the RPC-example folder on the 
disk. 

• Add the plist-server.c file from the RPC-example folder on the disk. 

• Add the RPC.lib library in the Libraries folder in the Maclvory Devel- 
opment folder. This library supports the Remote Procedure Call facili- 

ty. 

• Add the Maclvory.lib library in the Libraries folder in the Maclvory 
Development folder. This library supports the Ivory coprocessor. 

• Add the MacTraps library in the Mac Libraries folder in the THINK 
C folder. This library provides the interface to the Macintosh operat- 
ing system. 

• Click below the dotted line in the project window to select a new code 
segment. (Otherwise, the application will fail to link because it is too 
large.) 

• Add the ANSI library in the C Libraries folder in the THINK C fold- 
er. This library provides the interface to the Macintosh operating sys- 
tem. 

g. Click Cancel after adding those files, to get out of the file menu. Op- 
tionally, select [Project / Set Project Type] from the pull-down menu and 
check the Separate STRs box. Click on OK. (Otherwise you will get a 
"can't load STRS in this project" error.) 

h. Use [Project / Build Application] to compile, link, and produce the out- 
put, naming it Application-example. Note: you will be in Mac Libraries 
and will need to switch to RPC-example folder. Now you can use [File / 
Quit] to leave THINK C. 

Run the program. 

Follow these steps to run the program you just created. 

a. Double click on the Application-example icon you just created. 

b. Type a symbol into the dialog box that appears and press Return. The 
symbol's property list will be displayed in a window. 
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c. Drag down the File menu and mouse Plist to examine another symbol or 
mouse Quit to quit the program. 



Routines in RPC.lib 
Routines for Initialization 

InitializeRPC Routine 

void Initial izeRPCO 

Initializes the RFC library. You must call InitializeRPC before calling anything 
else in the RFC library. 

initialize_reinote_inodule_naine_server Routine 

OSErr initial ize_remote_module_name_seryer{) 

Every linked remote module server defines a C routine named 
initiaMze_remote_module_name_server, where remote jnodulejiame is the name of 
the remote module, converted from Lisp syntax to C syntax (lower case letters, hy- 
phens replaced by underscores). You must call each of these routines after calling 
InitializeRPC, to allow incoming RFC calls from the Ivory to find these servers. 

initialize_predefined_remote_entries_server Routine 

This server is in the RFC library, so it is always present. You must call it after 
calling InitializeRPC. See the section "im.iialize_remote_module_name_s,erYer Rou- 
tine". 

emb_agent_open Routine 

OSErr emb_agent_open() 

Establishes a bidirectional RFC channel between the host Macintosh and the em- 
bedded guest Ivory. emb_agent_open returns a standard Macintosh error code. If the 
value is not noErr, you should terminate the application. 

Note: It is important to check this error code. Use the ReportRPCOpenFailure rou- 
tine to report problems. 

Routines for Termination 
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CloseRPC Routine 

void CloseRPCO 

Releases the bidirectional RFC channel between the host and the embedded guest 
Ivory. 

Maclvory User Note: Before your application exits, it must call CloseRPC or the 
RFC channel allocated by emb_agent_open will remain permanently busy. Your 
RestartAppl i cations routine must call CloseRPC and then call emb_agent_open again. 

Routines for the Event Processing Loop 

PoURPC Routine 

void PollRPCO 

Handles incoming requests and responses from Ivory. Pol 1 RPC must be called peri- 
odically, typically from your application's main event loop. Pol 1 RPC can call back to 
BusyWait and to RFC servers. 

BusyWait Routine 

void BusyWait(Boolean allow_rpc) 

Your application must define the function BusyWait, to be called by the RFC library 
when it needs to wait. BusyWait should perform whatever polling you require once 
and then return; it should not loop. 

The RFC library calls BusyWait repeatedly until the condition for which it is wait- 
ing is satisfied, al 1 ow_rpc is TRUE if the RFC system expects you to call it back, 
and FALSE if it does not. Call Pol 1 RPC if and only if al 1 ow_rpc is TRUE. 

Symbolics UX User Note: Be careful that BusyWait is not run in a tight loop. See 
the section "Interfacing the Symbolics RFC Library to an Event Loop". 

Maclvory User Note: BusyWait gives you an opportunity to implement whatever 
multiprocessing strategy you prefer. When using MultiFinder, BusyWait must call 
GetNextEvent or WaitNextEvent so that other Macintosh applications can run. In 
general, it is a good idea for BusyWait to support the mouse at least to the extent 
of allowing the Apple menu to be used, but it is not a good idea for BusyWait to 
run portions of your application that can make RFC calls to the Ivory. 

Maclvory Example: 

This example assumes: 

1. The program has a global Boolean variable, WNEIsImplemented, whose value 
is set by the following code fragment: 
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tfdefine WNETrapNum 0x60 

tfdefine UnlmplTrapNum 0x9F 

Boolean WNEIsImplemented; 

WNEIsImplemented = (NGetTrapAddress (WNETrapNum, Tool Trap) != NGetTrapAddress 
(UnlmplTrapNum, ToolTrap)); 

This variable tells the program whether to call GetNextEvent or WaitNextEvent. 



2. The program has a function called ProcessEvent to process events. 
Here's BusyWait: 

void BusyWait (allow_rpc) 
int allow_rpc; 

( 

EventRecord event; 
short mask; 

mask = (ColdLoadlsUisible ()) ? 

(everyEvent - keyUpMask - activMask) 

: (everyEvent - keyDownMask - keyUpMask - autoKeyMask 
- activMask - updateMask) ; 

if ( IWNEIsImplemented) 
SystemTask () ; 

if (allow_rpc) 

PollRPC 0; 

MacIvoryTasks () ; 

if ((WNEIsImplemented) ? WaitNextEvent (mask, &event, 2L, 0L) 

: GetNextEvent (mask, &event)) 
ProcessEvent (&event) ; 

UX Example: 

/*** Include Files ***/ 

^include <sys/types.h> 
^include <errno.h> 
^include "RPC.h" 
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/*** Required by the RPC library ***/ 

void BusyWait(al low_rpc) 
int allow_rpc; 

( 

int cc = 0, rpc_fd; 
fd_set read; 

/* Set up */ 

rpc_fd = RPCAgentFileDescriptorO ; 

for (; cc == 0;) ( 

/* Wait for something interesting to happen 

* We select for input ready on the RPC file descriptor. In a more 

* complex program, there may be other interesting file descriptors 

* or a timeout here. 
* 

* We ignore EINTR, which means we were interrupted by a signal handler 

* being called, and EWGULDBLGCK, which SunOS has been seen to return 

* inappropriately in this situation. 
*/ 

FD_ZERG(&read); 
FD_SET(rpc_fd, &read) ; 

if ((cc = select(rpc_fd+1, &read, NULL, NULL, NULL)) < && 
errno != EINTR && errno != EWGULDBLGCK) ( 

perror("BusyWait select"); 

exit(-1) ; 
} 

/* If there is input pending on the RPC fd, and we're allowed 

* to make recursive calls to the RPC substrate, do so. 
*/ 

if (cc > && FD_ISSET(rpc_fd, &read) && allow_rpc) 
PollRPCO; 
} 
} 



Routines for RPC Error Handling in RPC. lib 
RPCRemoteError Routine 
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RPCRemoteError (long *error-number) 

Returns the remote error number of the last RFC call that failed. This routine is 
useful with the individual functions that access remote-error values to allow error 
handling. 



ReportRPCOpenFailure Routine 

Boolean ReportRPCOpenFailure (OSErr error, Boolean embeddedP, char* host) 

Reports a failure when opening an agent (that is, when calling emb_agent_open). 
The argument error is the return code from the call. For now, embeddedP should 
be TRUE and host should be 0L. Returns TRUE if unable to recover from the error; 
returns FALSE if able to recover from the error and if the agent is open. 

ReportRPCCallFailure Routine 

Boolean ReportRPCCallFailure (Boolean fatal P, OSErr error, 

Boolean embeddedP, char *host) 

Reports a failure from an RFC call. The argument error is the return code from 
the call. The argument fatal P should be TRUE or FALSE based on whether the error 
can be recovered from. For now, embeddedP should be TRUE and host should be 0L. 
If fatal P is FALSE, this routine returns TRUE if the user decides to give up and re- 
turns FALSE if he wants to try again. If fatal P is TRUE, the routine always returns 
TRUE. 

Routines in Maclvory.lib 

Note: Frototypes and type definitions are in Maclvory-Support.h. 

Routines for Initialization 

InitMacIvorySupport Routine 

void InitMacIvorySupport(Boolean forMacIvory, int* YourResFile, 

WindowPtr* ColdLoadWindow, MenuHandle* 
IvoryControlMenu, Boolean* initedMacIvorySupport) 

Initializes the Maclvory library and opens its associated resource file, dis^:System 
Folder:Ivory:MacIvory-support.rsrc. The value of forMac Ivory is TRUE, if you ex- 
pect an Ivory coprocessor to be present in the system. It is FALSE if the library is 
present in your application, but you are not using the Ivory. In Maclvory pro- 
grams, forMac Ivory should always be TRUE. 

The remaining arguments are addresses of variables that receive return values: 
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YourResFile is set to the reference number of the apphcation resource file. Cold- 
LoadWindow is set to point to the Macintosh window that contains the cold-load 
stream. IvoryControlMenu is set to a handle to the Ivory menu, which you should 
add to the menu bar. The latter two variables are not set if forMac Ivory is FALSE. 
initedMacIvorySupport is set to TRUE if the library was initialized and will have 
to be shutdown by TermMacIvorySupport later. 



InitMacIvory Routine 

void InitMacIvory(Boolean NeedsLispRunning) 

Checks on the status of the Ivory coprocessor, initializes the coprocessor if it is 
uninitialized, and boots it, if needed. NeedsLispRunning is TRUE if Lisp must be 
running. It is FALSE if it is okay for just the IFEP to be running. 

Routines for Termination 

TermMacIvorySupport Routine 

void TermMacIvorySupport(Boolean forMacIvory) 

Shuts down the Maclvory library. If the Ivory is not running, relinquishes control 
of the network interface so other Macintosh applications can use it. Call this 
whenever an Ivory-using application exits. Supply the same value for forMacIvory 
as in your call to InitMacIvorySupport. 

ExitMacIvoryApplication Routine 

void ExitMacIvoryAppl icationO 

You must define this routine in your application. This routine is called by the li- 
brary if the application must be terminated unexpectedly. It should call Ter- 
mMacIvorySupport if the library is initialized. It should call CloseRPC if an agent 
was opened. In all cases it should also cleanup after the appplciation and Exit- 
toShell. 

OKtoStopMacIvory Routine 

Boolean OKtoStopMacIvory () 

Returns TRUE if it is okay to quit the application now; either the Ivory is not 
running or the user has confirmed that it is okay via an alert box. This routine is 
usually called in your handler for the "Quit" menu item. 
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RestartMacIvoryApplication Routine 

void RestartMacIvoryAppl ication() 

You must define a routine named RestartMacIvoryApplication, which is called 
with no arguments from MacIvoryTasks when the Ivory system is booted or restart- 
ed. RestartMacIvoryApplication should reset whatever is appropriate to reset in 
your application. You must call CloseRPC in this function and then open a new 
channel. 

RestartMacIvoryApplication can either return to its caller or perform a longjmp to 
the start of your application. 

Routines for the Event Processing Loop 

MacIvoryTasks Routine 

void MacIvoryTasksO 

MacIvoryTasks must be called periodically, typically from your application's main 
event loop. It handles reset requests from Ivory and maintains the cold-load-stream 
window. MacIvoryTasks can call back to ExitMacivoryAppl ication or NoteMacIvoryS- 
tateChange. 

MacIvoryEvent Routine 

Boolean MacIvoryEvent(EventRecord* Event, long* MenuAndltem) 

Your application's event processing loop should call MacIvoryEvent on every event, 
before processing it. 

MacIvoryEvent takes care of the Ivory menu and the cold-load-stream window. If 
MacIvoryEvent returns TRUE, it has fully handled the event and the application 
can ignore it. Otherwise, the application should handle the event normally. Howev- 
er, if the event is mouse-down in the menu bar, MacIvoryEvent has already called 
MenuSelect and set the variable addressed by MenuAndltem to the result, so the ap- 
plication should not call MenuSel ect again. 

NoteMacIvoryStateChange Routine 

void NoteMacIvoryStateChange (enum MacIvoryStateTransition state) 

NoteMacIvoryStateChange is called by the library whenever Ivory's state changes, 
for instance, when it shuts down or starts Lisp. You must define this routine in 
your application. Posssible state transitions are: 

Value of State Meaning 
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MacIvoryHasBroken Library has detected a fatal situation. Ivory may be unus- 
able. 

FEPHasStopped IFEP has shutdown. Ivory is no longer running. 

FEPIsRunning IFEP is booted. 

LispIsRunning Lisp has been cold or warm booted. 

LispHasStopped Lisp has halted or otherwise encountered a fatal condition. 



Control Routines in Maclvory.lib 

ColdLoadVisible Routine 

Boolean ColdLoadlsUisible (); 

Reports whether the cold load window is displayed. Returns a value of TRUE if 
the cold load window is currently on display (the frontmost window). Returns a 
value of FALSE if the cold load window is currently hidden. 

IsColdLoadWindow Routine 

Boolean IsColdLoadWindow (WindowPtr Candidate); 

True if Candidate is the cold load window. 

IsNetworkEnabled Routine 

Boolean IsNetworkEnabled (); 

True if Ivory has attached the Ethernet interface. 

MacIvorylsRunning Routine 

Boolean MacIvorylsRunning (); 

True if the Ivory coprocessor is running either Genera or IFEP. 

MacIvorylsRunningLisp Routine 

Boolean MacIvorylsRunningLisp (); 

True if the Ivory coprocessor is running Genera. 
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RunninglnBackground Variable 

Boolean RunninglnBackground 

A value of true indicates the application is running in the background under Mul- 
tiFinder. 

A value of false means the application is the selected application under MultiFind- 
er or is the only application under the Finder. 

myProgramlD Variable 

long myProgramlD 

A unique ID assigned by the Maclvory support library to the application. 

Routines for the Ivory Menu in Maclvory.lib 

Calling one of these entry points does exactly what the equivalent Ivory menu item 
does. If the menu item puts up an alert box asking for confirmation to complete 
an action, the equivalent entrypoint does the same. If the menu item puts up an 
alert box when and operation does not finish in time or fails, so does the equiva- 
lent entrypoint. 

ColdBootFEP Routine 

ColdBootFEP 0; 

Cold boots the IFEP. This is equivalent to the "Cold Boot FEP" item in the Ivory 
menu. 

ColdBootLisp Routine 

ColdBootLisp (); 

Cold boots Lisp. This is equivalent to the "Cold Boot Lisp" item in the Ivory menu. 

ContinueLisp Routine 

ContinueLisp (); 

Switches control from the IFEP to Lisp. This is equivalent to the "Transfer to 
Lisp" item in the Ivory menu. 

DisableNetwork Routine 
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void DisableNetwork (); 

Disables the Ivory's use of the Ethernet interface. 

EnableNetwork Routine 

void EnableNetwork (); 

Re-enables the Ivory's use of the Ethernet interface. 

HideColdLoad Routine 

void HideColdLoad (); 

Hides the cold load window. 

RestartFEP Routine 

RestartFEP (); 

Warm boots the IFEP. This is equivalent to the "Restart FEP" item in the Ivory 
menu. 

RestartLisp Routine 

RestartLisp (); 

Warm boots Lisp. This is equivalent to the "Restart Lisp" item in the Ivory menu. 

ShowColdLoad Routine 

void ShowColdLoad (); 

Call this to show the cold load window on the display. 

ShutDownlvory Routine 

ShutDownlvory (); 

Halts the Ivory. This is equivalent to the "Shut Down" item in the Ivory menu. 

StopLisp Routine 

StopLisp 0; 
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Switches control from Lisp to the IFEP. This is equivalent to the "Transfer to 
FEP" item in the Ivory menu. 



Developing User Interfaces with Maclvory 



How the Maclvory User Interface Works 

The Maclvory system user interface substrate is designed with flexibility in mind, 
so that applications can make maximally effective use of both of the co-processor 
systems. As much as possible, we have tried not to constrain decisions about user 
interface design by imposing fundamental limitations in the system. Choices can be 
made on an application-by-application basis by the application programmer. In 
some cases, it may even be possible to defer decisions to the final end-users by of- 
fering a variety of styles from which they choose. 

There are two main guiding forces in the way that Maclvory works. These are: 

1. Compatibility with other Symbolics products, especially the previous stand- 
alone proprietary platforms. 

2. Good, smooth integration with the Macintosh operating system and its user 
interface guidelines and conventions. 

These forces often work at cross-purposes. It sometimes is not possible to fulfill 
both sets of constraints simultaneously within a given interface. For this reason, 
we allow the the application programmer to decide how to balance these con- 
straints, and have made every effort to make this process as easy as possible. 

For instance, the generic file system model is used to provide access to both the 
native Macintosh file system and a local LMFS file partition on the Ivory partition 
of the disk. It is up to the user to decide where to store his or her files. 

Most important, perhaps, is how these principles apply to the user interface. 

The user interface is controlled by an application which runs on the Macintosh on 
behalf of the Ivory. The Ivory communicates to the Macintosh using a standard 
Remote Procedure Call facility (RPC) through a shared memory channel. The 
workhorse of this communication is a remote console protocol, by which the Ivory 
requests that the Macintosh draw lines, rectangles, characters, and the like. These 
requests are handled asynchronously; that is, the Ivory does not wait for the Mac- 
intosh to finish drawing. Higher-levels requests, such as reading user responses 
via a dialog window, obviously must wait. 

All drawing is handled by the Macintosh. Among other things, this means that any 
display monitor which works with QuickDraw will work with Maclvory. It also 
means that there is no array in Lisp virtual memory, which is mapped to an ex- 
posed window's portion of the display's frame buffer. 

The compatibility of the Maclvory system is not limited by the exact capabilities 
that the Macintosh provides in its high-level toolbox. 
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• The Apple user interface guidelines recommend very strongly against warping 
the mouse (cursor). However, a number of existing Genera applications rely on 
this capability for correct functioning. Therefore, the Maclvory provides the ca- 
pability and it is up to the application programmer to only use it wisely. 

• When copying from a small image to a larger one, the QuickDraw CopyBits pro- 
cedure will scale the image up linearly. The Genera bitblt primitives are de- 
fined to replicate the source image in these cases. Maclvory provides a fully 
compatible interface for copying from a raster array to the screen, with replica- 
tion. If necessary, more than one CopyBits call is performed to produce the de- 
sired result. 

• The QuickDraw line drawing interface does not provide a way of suppressing 
drawing of the final endpoint. The polygon drawing interface is not completely 
compatible with Genera's draw- triangle, which was specifically designed to allow 
triangles with common edges to abut seamlessly. Therefore interfaces to Genera- 
compatible line and triangle drawing are provided which work in terms of lower- 
level QuickDraw primitives, rather than LineTo or PaintPoly. 

• QuickDraw has a relatively fast character drawing entry. However, the normal 
Macintosh screen fonts are not compatible with Genera fonts. Therefore, 
Maclvory provides copies of all the standard Genera fonts in a format which the 
Macintosh can use for fast drawing. 

• QuickDraw patterns can only be 8x8 bits, no more, no less. The Genera graphics 
substrate provides more general pattern and stipple patterns. Therefore, the 
QuickDraw patterns are not normally used for stippling when strict compatibili- 
ty is enabled. 

Of course, all this compatibility comes with a performance penalty. Many applica- 
tions are prepared to trade strict compatibility for improved performance. For this 
reason, we provide access to drawing capabilities which more nearly match those 
provided natively by the host, while still maintaining the Genera user interface 
style. 

• If an application is using the Genera graphics:draw-xxx primitives, a single 
form is provided which enables use of QuickDraw's high level entries to accom- 
plish drawing. This device independence was one of the major criteria in the de- 
sign of Genera's unique graphics substrate. 

• Applications using the lower-level :draw-line and : draw- triangle messages can 
still enable a mode where these use QuickDraw lines and polygons. 

• A Genera-style interface application can be configured to use the Macintosh's 
native fonts instead of the default Genera fonts copied to the Mac, or to use 
smaller fonts to account for the smaller screens with a lower pixel density that 
are common on Macintoshes. If the application is using character styles, this 
change is mostly invisible. This independence was one of the major criteria in 
the design of Genera's unique characters substrate. 
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• Bit arrays which need to be copied to and from the screen can be stored on the 
Macintosh side and drawn into remotely there. The Macintosh application which 
runs on behalf of Ivory will also swap these back and forth from the disk as 
need be, so there is no practical limitation on their size or number, even though 
the Macintosh does not have virtual memory. 

Moving further away from compatibility, it is possible for a Genera application to 
make use of the Macintosh user interface toolbox, which comes with a well estab- 
lished reputation for ease-of-use. 

This access can be made directly by using the Lisp interface to the toolbox func- 
tions. However, we imagine that most Genera programmers are unaccustomed to 
having to deal at this low a level, and would prefer to use higher level-interfaces. 

Compatibility is also provided in user interface peripherals. 

• A number of large displays for the Macintosh approximate the size and pixel 
density of the standalone Genera workstation screens. 

• The Apple extended keyboard can be used to input all the characters that can 
be typed on the Symbolics keyboard. Of course, some of these combinations are 
awkward. For this reason, there is an option for a Symbolics keyboard which in- 
terfaces to the Apple Desktop Bus and is therefore fully usable with the Macin- 
tosh as well. Alternatively, a user can customize the mapping for the Apple ex- 
tended keyboard into the Symbolics keystrokes using an interactive program. For 
instance, we have found a wide difference in opinions as to how the three meta 
shift keys should be mapped into the three primary Symbolics shifts. 



• 



A three-button mouse option which connects to the ADB is provided for those 
applications which make heavy use of the middle and right buttons, which re- 
quire keyboard assistance without it. 



Basic Color Support in Maclvory 

If the host has color display hardware, you can draw in color by using the rcolor 
or :gray-level arguments to the graphics:draw-xxx functions. The value of :color 
is a symbol that names a color (one of rblack, :red, rgreen, :blue, :cyan, ryellow, 
rmagenta, rwhite), a list (red green blue) where each element is a number between 
and 1, inclusive, or a color object created by colorrmake-color. The value of 
:gray-level is a number between and 1, inclusive. 

See the section "Pattern Options". 
See the option rcolor. 
See the option rgray-level. 

In addition, when the host has color display hardware, the Genera window system 
can run in color mode or in monochrome mode. You must have the Ivory-Color- 
Support system loaded to use color mode. Both modes can draw in color. The dif- 
ference involves saving and restoring displayed images when switching windows. In 
monochrome mode, only one bit per pixel is saved, so when you switch windows 
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any colored drawings lose their color. In color mode, the complete image is saved 
including the color information. Color mode comes at a cost: a much larger 
amount of information must be transmitted to and from the screen. For example, 
in 8-bits-per-pixel mode switching windows requires eight times as much informa- 
tion transmission, and off-screen bit arrays require eight times as much host 
memory. Depending on the hardware configuration, storing and transmitting the 
extra information can slow down response to an unacceptable level. For this rea- 
son, the default mode is monochrome mode even when color display hardware is 
present. See the section "Configure Maclvory Application Command" for informa- 
tion on how to enable color mode. 

The above considerations also apply when the host has display hardware that can 
display shades of gray; that is, more than just black and white, but less than full 
color. In monochrome mode, the gray level is converted to black or white when 
switching windows; in color mode, the gray level is preserved at a cost in perfor- 
mance determined by the number of bits per pixel. 



colorrmake-color f&key :red :blue :green .-intensity :hue .saturation &allow-other- 
keysj Function 

Creates a color object. Color objects can be used with the rcolor argument to the 
graphics:draw-xxx family of functions. 

The arguments are numbers between and 1 inclusive, defaulting to 0. To specify 
a color in the RGB color model, specify one or more of :red, rgreen, and :blue. To 
specify a color in the IHS color model, specify one or more of rintensity, :hue, and 
: saturation. 



Higher-level Interfaces to the Macintosh Toolbox 

If you are not concerned with compatibility among platforms, you may wish to con- 
vert your program to have a Macintosh- style user interface. A specialized version 
of dwrdefine-program-framework is provided with capabilities that implement the 
Macintosh- style user interface. These capabilities include: 

• Use of hierarchical pull-down menus from the menu bar to implement program 
command levels of menus and subcommands. 

• Stream output to Macintosh windows, either in realtime, or via a picture record 
structure which gives a window that can be scrolled entirely on the Macintosh 
side. 

• Use of dialog boxes for dwraccepting-values. 
The major pieces of this facility are: 

• dwrdefine-remote-program-framework, which controls layout of the menu bar 
among command menu items. 
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• dwrwith-remote-accepting-values, which gives access to dialog boxes for accept- 
ing-values. This is also invoked automatically if you give :menu-accelerator for 
a command. 

• dw:with-output-to-viewer, which allows stream output to a Macintosh window. 

If you plan to use these facilities, you may wish to consult your Maclvory customer 
support contact. Limited resources and the requirement of compatibility among all 
system products did not permit the actual conversion of any Genera applications to 
have Macintosh- style user interfaces. 

For examples of the use of these facilities, see the section "Example of Converting 
an Application for Maclvory". 



Functions for Creating Macintosh-style Interfaces 



dwrdefine-remote-program-framework name &body options &key (xommand- 
definer t) :menu-level-order stop-level .-command-table :inherit-from .state-variables 

Special Form 

A subset of dwrdefine-program-framework, which implements a program that can 
be run using the Macintosh- style user interface. Each menu level specifies a col- 
umn in the pull-down menu. Releasing the mouse on a given item is equivalent to 
clicking on that item in the Genera style interface. Normally, menu items are 
filled in by means of the :menu-accelerator option to a program command defini- 
tion. 

The :name, rcommand-definer, :top-level, :command-table , :inherit-from, rstate- 
variables, and :pretty-name options are just as for dwrdefine-program- 
framework. 

The rselectable option is slightly different, in that it can also be a list of remote 
system types. For instance, rselectable (rmac) would mean that the program could 
be started up as a Maclvory application, but would not appear in the Select Activi- 
ty menu, rselectable t means that a remote host can start up the application using 
its interface style, and Select Activity will start up the same application using the 
Genera style (even on a Maclvory, when it is running the Genera application). 

The rmenu-level-order option represents a list of lists (evaluated) of item names 
(or nil for empty slots) specifying how the items in specific columns are laid out. 
If you do not give this explicitly, the order of columns is unpredictable, and the or- 
der within columns tends to be alphabetical. 

Example: 

: menu-level -order ' (, macintosh-internals: :*standard-remote-vi ewer-file-menu* 

, maci ntosh-i nternal s : : *standard-edi t-menu* 
"Lookup") 
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dwrremote-program Flavor 

The basic flavor included in programs running with the host user interface style. 

dwrremote-program-quit &optional (program dw:*prograin*J Function 

Exits the host application corresponding to this program. On the Macintosh, this 
closes all its windows back to the icon. 

Normally, this is accessed with the Quit command in the remote-quit-commands 
command table (which you can inherit). But sometimes a program wishes to do it 
for other reasons. 

dwrremote-program-p local-program Function 

Returns t if the program is using the host user interface. Useful for large-scale 
conditionalization of behavior in a program which also works with the Genera-style 
interface. 



dwrwith-remote-accepting-values &optional (stream *query-io*J &key (-program 
dw:*prograin*J .-prompt Function 

Like dwraccepting-values, but uses the host dialog style if the program uses the 
host interface style. On the Macintosh, the host dialog is constructed by classifying 
each query in the body (that is, each call to accept) as one of the following: 

• A boolean choice 

• An enumeration from an explicit set 

• An arbitrary string 

These are laid out (automatically) in a dialog menu as check boxes, radio buttons, 
and text fields, respectively. 

Most often, this capability is accessed for the command arguments to a program 
command given with rmenu-accelerator, when the user releases the mouse on the 
corresponding item. 

dw: def ine-remote-progr am-cominand Function 

Like dwrdefine-program-command. Almost always accessed via the define-xxx- 
command macro generated by the rcommand-definer option to dw: def ine-remote- 
progr am-framework. 

If rmenu-accelerator is given, a menu item is added to the host command menus 
for this command. If the command takes arguments, selecting this item gives a di- 
alog box for those items. Otherwise, it runs the command immediately. 

The format of rmenu-level is extended slightly. The elements of the list are names 
of levels in the Genera style interface (often keywords), or lists of a remote system 
type and level within the interface for that system. The next example puts the 
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item in the main menu, if Genera-style, and in the Commands pull-down menu, if 
Macintosh style. 

(def ine-my-command (com-show-doc : menu-accelerator "Show" 

: menu-level (: top-level (:mac : commands)) 
: keyboard-accelerator tfXs-S) 
...) 



dw:with-output-to-viewer f&optional stream &rest args) &body body Special Form 

Adds output from body to the program's display. If the program is using the Gen- 
era-style interface, the primary pane has its contents replaced with those obtained 
by the body. The window's label is set to the title, if any. The other options are 
ignored. 

If the program is running using the Macintosh- style interface, a new window is 
created. The options work as follows: 



:progress-note 
:picture-p 



rtitle 



If given, the watch mouse icon is shown while the output is 
being computed. 

If nil, the window does not have any contents initially and 
nothing is regenerated automatically when the screen area is 
disturbed on the Macintosh side. 

If non-nil, the output is buffered into picture records that are 
remembered on the Macintosh side. The window can then be 
scrolled and refreshed entirely by the host. 

Gives the string for the title bar. 



rwidth, rheight, :left, :top, rright, rbottom 

These specify the location and size. The default is positioned 
slightly offset from other windows and as large as picture con- 
tents, if any, or the entire screen if not. 

:color-p Makes a color Macintosh window rather than an old-style one. 

This allows use of the rcolor keyword within the output body 
to work properly with graphics:draw-xxx. 

rbuffer-screens Exposes the window as soon as the first screenful of output 
has been collected. If the window is then scrolled remotely past 
the end of the output known to the Macintosh, the next screen- 
ful is requested of the guest. 

:buffer-ahead-screens 

Used with :picture-p t, this option specifies the number of 
screenfuls to keep buffered past the visible end. This makes 
scrolling one screen at a time not pause as often, assuming the 
user stops to read each screenful. 
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If present or dw:with-output-as-presentation is used within the output body, the 
corresponding output can be sensitive when using the host user interface. For the 
Macintosh, a rectangle is inserted containing sensitive items while the mouse is 
held down, and the corresponding action taken when the mouse is released. These 
actions are defined in the normal way with define-presentation-translator. At 
present, only translation to program commands works (that is, there is only one 
valid input context). 



Program: Macintosh-internals:remote-quit-commands 

Defines the Quit command, with the s-Q command accelerator. You can inherit 
this program and its command table to get the command. 



Program: Macintosh-internals:remote-viewer-commands 

Defines commands useful for dealing with stacks of windows generated by 
dw:with-output-to- viewer : 

Close (s-W) closes the front window. 

Close All closes all windows for this application. 

This program also depends on the remote-quit-commands program, which means 
you get the Quit command also when you include it. 

For example, 

(dw : def i ne-remote-program-f ramework my-program 
: selectable (:mac) 

: menu-level -order ' (, macintosh-internals: :*standard-remote-vi ewer-file-menu* 
, maci ntosh-i nternal s : : *standard-edi t-menu* 
"My commands") 
: inherit-f rom (macintosh-internals: : remote-viewer-commands) 

: command-table ( :kbd-accelerator-p t : inherit-f rom '("remote-viewer-commands")) 
) 



Macintosh Notes for dw:define-subcommand-menu-handler 

If you use the function dw:define-subcommand-menu-handler in a Macintosh- 
style program, you get a hierarchical pull-down menu. For example, 

(dw:def ine-subcommand-menu-handler "More Tests" test ((:mac :test)) 
(:mac : more-tests)) 



Creating a Macintosh Application That Runs an Ivory-based Program 
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This section describes how to create a Macintosh application that provides the user 
interface for your Ivory program. Before doing so, you must have created the Ivory 
portion of your application with dwrdefine-remote-program-framework. You must 
also load your program framework into Genera. 

The Configure Maclvory Application command creates a Macintosh program using 
the values you provide. This program provides the user interface. See the section 
"Configure Maclvory Application Command". A double click on the resulting Macin- 
tosh application icon will communicate with the Ivory through RPC and run your 
application. 



Creating a Macintosh Application That Uses the Genera Window System 

To create a Macintosh application that runs an Ivory-based program under the 
Genera window system, rather than the Macintosh's own window system, use the 
following procedure. Configure a copy of the Symbolics-supplied "Genera" Macin- 
tosh application that uses the "Start Screen" initial application command to start 
up your application. After filling out the first four lines of the form, click on "a 
GENERA command", type Start Screen followed by a space, and type in the argu- 
ments to the command. If you press n-COMPLETE after Start Screen, you will see a 
menu of the command arguments. For most purposes you can press RETURN After 
the first two arguments. 

This works for any application that can be started by the Select Activity command. 
For example, to create a Macintosh application that runs the Zmacs editor: 

:Configure Maclvory Application 

From file: HOST :DSK:Genera 

To file: HOST:DSK:Editor 

Application: None Genera 

Version: 1.0d0 

Agent: Top Serial Reliable-Serial Emb 

Initial application command: None Start Screen Genera fonts installed 

on Mac "Zmacs" 



Creating and Using Macintosh Dialogs 

Sometimes it may be necessary to exert more control over the appearance of Mac- 
intosh dialogs than dwrwith-remote-accepting-values allows. By dealing with 
things at a somewhat lower level, you can do it. 

You create a dialog m,aker, which is an instance of flavor mtb:dialog-item-maker, 
and use various generic functions with it. You may add dialog items, specifying 
their individual type, location, and so on, along with a symbolic query id. You may 
specify the edges and window type of the dialog window itself. And, finally, your 
dialog maker can interact with the user with a modal dialog; the user's choices, 
selections and entries are returned in plist form with the query ids. 
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Make a dialog maker with mtbrmake-dialog-itein-inaker. Add dialog items to it 
procedurally with mtbradd-dialog-button, mtb:add-dialog-text, mtbradd-dialog- 
edit, mtb:add-dialog-check, mtb:add-dialog-radio, mtb:add-dialog-pict, and 
mtb:add-dialog-line. If you have the appropriate data structure in hand, add dia- 
log items declaratively with mtb:add-several-dialog-items. Control dialog item 
clustering with mtbrin-dialog-cluster. Specify aspects of the dialog window itself 
(as opposed its the dialog items) with mtb:set-dialog-face. 

Having specified the dialog items and window, use mtb:do-modal-dialog to show 
the window and handle the modal dialog interaction. 



Dialog Item Clusters 

Dialog items within a dialog can be grouped by cluster. Presently, clusters are use- 
ful only for mutually exclusive radio buttons: in such a cluster, when you click on 
one radio button to turn it on, the others in the same cluster are turned off. 

The Lisp model for every dialog item contains a cluster id. Dialog items are con- 
sidered to be in the same cluster if they have the same cluster id. Cluster ids are 
compared with eql. 



mtbradd-dialog-button dialog-item-maker rect title &key .-cluster .-active .-check 
.-query-id Function 

Adds a Button dialog item to dialog-item-maker. 

See the section "add-dialog-item Arguments". 

mtbradd-dialog-check dialog-item-maker rect title &key .-active .-report .-cluster :over- 
see-cluster .state :query-id Function 

Adds a checkbox dialog item to dialog-item-maker. 

See the section "add-dialog-item Arguments". 



mtb:add-dialog-edit dialog-item-maker rect &key .-text .-query-id .-required .-oversee- 
cluster Function 

Adds an editable text item to dialog-item-maker. Initial contents may be specified 
with rtext. 

See the section "add-dialog-item Arguments". 



mtb:add-dialog-line dialog-item-maker rect Function 

Draws a line on the dialog window, perhaps to separate groups of dialog items. 
The line is drawn with a 50%-density stipple, with a pen two pixels wide, from the 
top left of rect to its bottom right. 
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mtbradd-dialog-pict dialog-item-maker rect resource-id &key .-active .-check .-cluster 
.-query-id Function 

Adds a PICT dialog item to dialog-item-maker, resource-id is the PICT resource id 
of the picture. Your application will have to arrange for the appropriate resource 
file to be open when the PICT is to be drawn. 

See the section "add-dialog-item Arguments". 



mtbradd-dialog-radio dialog-item-maker rect title &key .-active .-report .-cluster :over- 
see-cluster .state :query-id Function 

Adds a radio button dialog item to dialog-item-maker. 

See the section "add-dialog-item Arguments". 

Radio buttons in the same cluster are mutually exclusive: when you click on one to 
turn it on, the others in the same cluster are turned off. See the section "Dialog 
Item Clusters". 



mtbradd-dialog-text dialog-item-maker rect text Function 

Adds static text to dialog-item-maker. 

See the section "add-dialog-item Arguments". 

mtb:add-several-dialog-items dialog-item-maker spec-list Function 

Adds several dialog items to dialog-item-maker under control of spec-list. 

spec-list is essentially an abbreviation for separate calls to add-dialog-xxx. The 
first element of each spec in spec-list is a keyword, as in the table below. The rest 
of each element becomes the rest of the args to the corresponding function. 

Keyword Function 

button mtbradd-dialog-button 

check mtb:add-dialog-check 

edit mtb:add-dialog-edit 

line mtb:add-dialog-line 

pict mtbradd-dialog-pict 

radio mtbradd-dialog-radio 

text mtbradd-dialog-text 

In addition, you can use the keyword rcluster as in (: cluster cluster-name &rest 
spec-list) to abbreviate calls to mtbrin-dialog-cluster. 

For example, see the file syS:EMBEDDING;MAC1vory;TOOLbox;EXAMpleS;XXX. 
mtbrdo-modal-dialog program dialog-items Function 
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In the context of the remote program program, does the modal dialog specified by 
the dialog item maker dialog-items. Exposes the dialog window, and repeatedly 
calls ModalDialog with a Lisp event filter callback. Handles clicks on check boxes 
and clustered radio buttons. Handles interaction with TextEdit. Returns when the 
user clicks on either of the first two dialog items (assumed to be buttons named 
"OK" and "Cancel"), or presses RETURN, ENTER or END. 

Also terminates when the user preses COMPLETE (the key labelled "HOME") or HELP 
in an editable text field. 

The value returned by mtb:do-modal-dialog is a plist of alternating query-ids and 
values. Each query-id comes from the :query-id argument to the add-dialog-xxx 
which created the dialog item. The corresponding values are strings (for editable 
text items), or t (for check boxes and radio buttons, when checked). Although a 
cluster of mutually exclusive radio buttons would be better modelled as a choice 
from an enumeration, there is no automatic support for returning this as a value 
for a specific query. 



mtbrin-dialog-cluster (dialog-item-maker cluster-id) &body body Macro 

Within body, provides implicit rcluster cluster-id arguments for calls to mtbradd- 
dialog-button, and so on. See the section "Dialog Item Clusters". 



mtbrmake-dialog-itein-inaker Function 

Makes a dialog item maker. 

See the section "Creating and Using Macintosh Dialogs". 



mtbrset-dialog-face dialog-item-maker &key .-bounds .-title :proc-id :go-away 

Function 

Specifies the appearance for a dialog window (as opposed to that of its dialog 
items). 

dialog-item-maker 

keywords rbounds, rtitle, :proc-id, and :go-away. 

rbounds A list (left top right bottom) or a Rect octet structure. Speci- 

fies the edges of the window, defaulting to (40 40 440 340). 

:title A string. Appears in the window's title bar, if any. 

:proc-id A small integer. Controls the shape of the dialog window. See 

Inside Macintosh, page 1-273. For example, to get a plain rect- 
angular box, use (mtbicconstant plainDBox); for a "rounded- 
corner" window with black title bar you would use 

(mtbicconstant rDocProc). 
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:go-away A boolean. Specifies whether there should be a go-away box in 

the top left of the corner of the window. 



add-dialog-item Arguments 

mtbradd-dialog-button, mtb:add-dialog-text, mtb:add-dialog-edit, mtbradd- 
dialog-check, mtb:add-dialog-radio, mtb:add-dialog-pict, and mtb:add-dialog-line 

all take the current dialog-item-maker as first argument. Several of them share 
other arguments: 

rect Specifies the edges of the dialog item, as a list (left top right 

bottom) or a Rect octet structure. 

title A string. Specifies the text, if any, displayed with the dialog 

item. 

query-id May be any Lisp object. Identifies the query in the plist re- 

turned by mtb:do-modal-dialog. 

cluster Any Lisp object. Groups dialog items together. See the section 

"Dialog Item Clusters". 



Low-level Interfaces to the Macintosh Toolbox 



Overview of the Low-level Interfaces 

Lisp programs on the Maclvory have complete access to the Macintosh User Inter- 
face Toolbox by means of the Remote Procedure Call (RFC) mechanism. Maclvory 
provides predefined remote entries that you can use to access Macintosh toolbox 
routines. There is no need to write your own remote entries. These routines can 
be found in the mtb (mac-toolbox) package. 

This means, for example, that if you are running an application on Maclvory and 
you want to make use of the Macintosh StandardFile package to prompt the user 
for the name of a file in the Macintosh file system, you can call the Lisp function 
mtb:_sfgetfile (the underscore is a naming convention that distinguishes the Lisp 
versions of Macintosh toolbox routines). 

The code on the Macintosh side that enables this is stored in a resource file recog- 
nized by the RFC mechanism. When a program using RFC on the Macintosh en- 
counters a call to one of the toolbox routines it will load the necessary resource 
and run the routine. 

To allow the greatest possible functionality, we have implemented all the routines 
described in volumes I through V of Inside Macintosh with the exception of Ap- 
pletalk Manager routines. For a complete list, see the section "Lisp Functions That 
Access the Macintosh Toolbox". 



Page 958 



Note that this hst includes routines that may make no sense to call while running 
the Genera application on the Macintosh. For example, calling the Lisp function 
mtb:_exittoshell would cause the Genera application to exit, probably without do- 
ing necessary cleanup. 

Predefined Types 

Mac type Lisp type 

struct name octet-structure — available by saying (mtb:make-name ...) as 

in (make-point :x 10 :y 20) or (make-sf reply). These provide 
accessors and init options for each of the slots. 

array A Lisp vector 

pointer fixnum (the Macintosh address) 

integer fixnum 

floating points float 

boolean nil or non-nil 



Conventions Used by the Maclvory Toolbox Interface 

Routine Names 

Lisp function names are identical to the Pascal names mentioned in Inside Macin- 
tosh. The only differences are that Lisp functions are identified by a preceding un- 
derscore and are not case sensitive. 

For example, the Macintosh function GetResource is called with the Lisp function 
mtb :_getresource. 

Arguments and Values 

Another difference between the Lisp versions of these routines and the Inside Mac- 
intosh Pascal versions is the handling of VAR parameters. The rule of thumb is 
that any VAR parameters that are structures (vectors in Lisp) of a size greater 
than one longword are overwritten with the value returned from the remote call. 
If there are other values to return, as in the case when a toolbox routine is a 
function, they are returned as multiple values with the function value first and the 
VAR parameters following in order of passing. 

When in doubt, remember that the command Show Function Arguments (c-sh-R) 
will show you the arguments and the values returned for the toolbox functions. 
The argument names are the same as those used in Inside Macintosh except in 
cases where "in" and "out" have been appended to the argument name to indicate 
that the argument will be overwritten. 
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Error Signaling 

Those Toolbox routines that are hable to generate an error, that is, those that re- 
turn a value of type OSErr, use the RPCError facility to signal errors in the Lisp 
function that calls them. This means that if you are expecting an error result 
from a function, and would like to take some action on encountering an error, you 
can use the Lisp condition handling mechanism to react to the error. The excep- 
tions to this are those functions such as _memerror and _reserror whose sole job 
is to check for error conditions and functions such as _sysenvirons that can re- 
turn error code and real data. 

IVIemError, ResError, and PrError 

To avoid having to do two RPC calls for every memory manager, resource manag- 
er, or printing manager routine — one for the routine and one to check for errors — 
the interface to these managers makes the appropriate call for you and signals an 
error when needed. 

You still need to do error handling in your RPC calls, but the appropriate error 
function is checked for each call to the memory manager, resource manager and 
printing manager routines. 



Predefined Macintosh Types 

In order to make writing RPC remote entries and using the toolbox interface easi- 
er, Maclvory software defines a number of the Macintosh types using the RPC da- 
ta type extension mechanism (see the section "The RPC Data Type Extension Lan- 
guage"). These types include most of the types described in Inside Macintosh, Vol- 
umes I through V. Understanding the correspondence between the types on the 
Macintosh and the associated Lisp types is important when using the toolbox in- 
terface. 

There are two categories of types: simple types and compound types. Simple types 
mostly correspond directly to Macintosh types in name and fun ctionality. Com- 
pound types are represented in Lisp as structures that correspond to Macintosh 
Record types. When a Toolbox routine is expecting a simple type like an integer, 
pointer, or floating-point, you can use the corresponding Lisp type. When the argu- 
ment is a Macintosh Record, you should create the structure in Lisp, as described 
below, and use that as the argument. 

Simple Types 

For most types the correspondence between the Lisp and the Macintosh types is 
simple. For example, if a Toolbox routine requires a specific numeric type such as 
Fixed for one of its arguments, you can just pass the routine a Lisp floating-point 
number, as in this example: 

(mtb:_spaceextra 1.3) 
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RPC translates the Lisp floating-point into the appropriate representation for the 
Macintosh type, in this case the Fixed type. 

Routines expecting integer types such as long and word can be called by just pass- 
ing in a Lisp integer of the appropriate size, as in this example: 

(mtb:_textsize 12) 

Macintosh pointer and handle types are 32-bit integers and can be manipulated as 
Lisp integers. For these types RPC takes care of all the data transport issues: con- 
verting from Lisp types to Macintosh types, doing the byte-swapping when needed, 
and converting the answer back from the Macintosh representation associated Lisp 
type. 

Compound Types 

There are a significant number of compound types defined in Inside Macintosh, 
Volumes I through V, that the Macintosh Toolbox routines need to be able to ac- 
cept as arguments. In order to allow you to manipulate objects of types, and to use 
them as arguments to Lisp Toolbox routines, there is a corresponding set of Lisp 
structure types. These types are implemented as octet-structures, and provide asso- 
ciated constructor and accessor macros. 



Using Octet Structures 

Octet-structures are art-8B (unsigned-byte 8) arrays with their own set of func- 
tions for accessing and manipulating slots. Using octet-structures allows you to 
create and manipulate a structure in Lisp that can then be sent across RPC with 
virtually no further translation. That is, it provides a uniform representation of 
the data across both machines. This is a convenient way to manipulate data in 
Lisp in the same byte format that is used on the Macintosh. 

Here's a simple example of using one of these octet-structures, mtbrdatetimerec, 
to set and read the time on the Macintosh. Notice that the constructor and acces- 
sor naming convention is the same as for Lisp structures. 

The Macintosh record DateTimeRec has slots for year, month, day, hour, minute, 
second, and day of week. This data structure might be defined in C as follows: 

typedef struct 



int 


year; 


int 


month; 


int 


day; 


int 


hour; 


int 


minute; 


int 


second; 


int 


dayOfWeek; 


} DateT 


imeRec ; 
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Because there is a corresponding octet-structure definition in Lisp, you can set the 
time on the Macintosh with: 

(let ((date (macintosh-internalsimake-datetimerec 
:year 1988 
: month 10 
:day 28 
:hour 13 
:minute 15 
: second 
:dayofweek 6))) 
(mtb:_setdatetime (mtb:_date2secs date))) 

Notice how you can construct a DateTimeRec in Lisp by using the constructor de- 
fined by the octet-structure. You can use accessors like mtb:datetimerec-hour to 
look at or alter the slots of the structure. 

Another common use of these structures is to get values back from calls to the 
Macintosh toolbox. For example, to read the date: 

(let ((date (macintosh-internalsimake-datetimerec))) 
(mtb:_secs2date (mtb:_getdatetime) date) 
(rpcidescribe-octet-structure 'macintosh-internalsidatetimerec date 0)) 

YEAR[0]: 1990 

MGNTH[2]: 10 

DAY[4]: 28 

HGUR[6]: 13 

MINUTE[8]: 25 

SECGND[10]: 51 

DAYGFWEEK[12]: 6 
NIL 

In this case you first create the structure to hold the value returned by the RFC 
call. It is then overwritten by RFC when the Macintosh call returns, just as the 
Fascal VAR argument would be. 

As you can see above, the Lisp function rpc:describe-octet-structure is often use- 
ful for examining these structures. 



Defining Octet Structures 

Most of the octet-structure types that you will need when writing code that inter- 
faces to the Macintosh from Lisp are already defined for you. However, if you need 
to access internal data- structures in MacOS, or write interfaces to already existing 
programs running on the Macintosh, you may run into the need to define your own 
octet-structure types. The following section describes the mechanisms provided for 
defining octet-structures. 
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Forms to Define Octet Structures 



rpc:define-octet-structure name-and-options &body fields 
Defines an octet structure. 



Macro 



name-and-options 



The name of the octet structure or the list containing the 
name of the structure and some number of keyword value 
pairs. 



This macro takes the keyword arguments :conc-name, rconstructor, rdefault- 
pointer, and rinclude, which behave in a way similar to the corresponding key- 
words for defstruct. See the section "Options for defstruct" for further informa- 
tion. In addition, rpc:define-octet-structure takes the following keyword argu- 
ments: 

:access-type Specifies how references are made by default as one of roctet, 

:unsigned-8, or :byte-swapped-8. To define octet structures to 
represent Macintosh structures, for use by the Toolbox remote 
entries, always use :byte-swapped-8. The default is roctet. 

ralignment Controls the automatic insertion of padding. This is useful 

when defining structures that you want to correspond directly 
to structures defined in another language or on a different ar- 
chitecture or both, ralignment takes an integer value as an 
argument. Specifying an alignment of n means that all struc- 
ture fields of size greater than or equal to n should be aligned 
with the next offset evenly divisible by n. Where the field is a 
vector it will be aligned based on the element size of the vec- 
tor. 

For example, when defining octet-structures in Lisp to repre- 
sent C structs as defined by THINK C on the Macintosh, you 
will want to specify an alignment of 2. This will align all 
structure fields of 2 or more bytes to an even byte boundary, 
and make sure that the Lisp accessors defined by rpcrdefine- 
octet-structure correspond precisely to where the data is 
stored by C. In any situation where you are using octet- 
structures to represent data that is created by one 
machine/language and manipulated by another, it is essential 
that you take into account the storage conventions of the other 
implementation. 

rdefine-accessors Inhibits definition of macros. 

rexport As for defstruct, takes a list of keywords from the set (rstruc- 

ture-name raccessors rconstructor). 

rdefault-type An integer type. :integer-8 is the default. 



Page 963 



: default-index Makes the second argument to each accessor optional, default- 

ing it to the value you supply with this argument. 

Elements of fields can be a symbol for single unsigned byte fields, or a list of field 
name and type. * used for a name allocates space, but doesn't define accessors. * 
used as a type defines subfields that overlap, such as bit fields. + used as a name 
defines unions. 

Examples 

These examples show the C types and corresponding octet-structure definitions for 
Point, Pattern, and Penstate. 

Point 

typedef struct 

( 

int v,h; 

} Point ; 

(def ine-octet-structure point : access-type :byte-swapped-8 

:defaul t-type :integer-16 
vertical 
horizontal ) 

Pattern 

typedef unsigned char Pattern[8]; 

(def ine-octet-structure pattern : access-type :byte-swapped-8 

:defaul t-type :integer-16 
(data (vector unsigned-8 8))) 

Penstate 

typedef struct 

( 

Point pnLoc; 

Point pnSize; 

int pnMode; 

Pattern pnPat; 

} PenState; 

(def ine-octet-structure pen-state : access-type :byte-swapped-8 

:defaul t-type :integer-16 
(pen-loc point) 
(pen-size point) 
(pen-mode integer-16) 
(pen-pattern pattern)) 



Page 964 



An octet structure that includes elements of a C structure: 

(def ine-octet-structure total 
(one one-type) 
(two two-type) 
(three three-type)) 

An octet structure that includes elements of a C union: 

(def ine-octet-structure general 
(+ ((one one-type)) 
((two two-type)) 
((three three-type)))) 

The slight differences being that we do not name the subsets, just the fields, and 
that we always have a level of parens, instead of requiring a recursive struct when 
the union element has more than one field. The differences between defining octet 
structures that include C members and those that include C unions is that for 
member, fields are named, but subsets are unnamed and 

Complex Example 

A more complex example, which cannot be written in C or Pascal, has several vari- 
able length fields. Notice that the size of one field can depend on the contents of a 
different, preceding field: 

(def ine-octet-structure font-header : access-type :byte-swapped-8 

idefaul t-type :integer-16 
(font-type cardinal-16) 
(first-char integer-16) 
(last-char integer-16) 
(width-max integer-16) 
(kern-max integer-16) 
(ndescent integer-16) 
(rect-width integer-16) 
(rect-height integer-16) 
(owt-loc integer-16) 
(ascent integer-16) 
(descent integer-16) 
(leading integer-16) 
(row-words integer-16) 

(bit-image (vector integer-16 (* rect-height row-words))) 
(location-table (vector integer-16 (+ (- last-char first-char) 3))) 
(offset-width-table (vector integer-16 (+ (- last-char first-char) 3))) 
) 
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(def ine-octet-structure font-family-header : access-type :byte-swapped-8 

:defaul t-type :integer-16 
(flags (* integer-16 

(image-height-p (boolean-bit 0)) 

(character-width-p (boolean-bit 1)) 

(f ract-enable-ignore (boolean-bit 12)) 

(use-extra-width (boolean-bit 13)) 

(use-f ract-width-table (boolean-bit 14)) 

(f ixed-width-p (boolean-bit 15)))) 
(family-id cardinal-16) 
(first-char integer-16) 
(last-char integer-16) 
(ascent f ixed-point-4+12) 
(descent f ixed-point-4+12) 
(leading f ixed-point-4+12) 
(width-max f ixed-point-4+12) 
(width-table-offset integer-32) 
(kern-table-offset integer-32) 
(style-table-offset integer-32) 
(style-properties (vector f ixed-point-4+12 9)) 
(intl (vector integer-16 2)) 
(version-number integer-16) 
(associ ati on-tabl e f ont-f ami 1 y-associ ati on-tabl e) ) 



rpc:define-octet-structure-field-type name type-arglist reference-arglist &body claus- 
es Macro 

Defines a new octet-structure field type. Clauses are :size, :data, or rexpander. 

Here's a simple example from the system. OSTYPE is the Macintosh type for a 
string of four bytes. By providing a mechanism for retrieving four bytes from the 
structure at the appropriate index, and a way to alter the slot, any subsequently 
defined octet-structure can have a field with this type and automatically generate 
the appropriate setfable accessor. 

(def ine-octet-structure-f ield-type ostype nil (array index) 
:size 
4 

:data 
' (ostype-f rom-subarray , array , index)) 

(defun ostype-from-subarray (array index) 
(let ((result (make-string 4))) 
(dotimes (j 4) 

(setf (aref result j) (code-char (aref array (+ j index))))) 
result)) 
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(defun set-ostype-from-subarray (array index value) 
(setq value (string value)) 
(check-type value (vector string-char 4)) 

(dotimes (j 4) (setf (aref array (+ j index)) (char-code (aref value j)))) 
value) 

(defsetf ostype-f rom-subarray set-ostype-from-subarray) 
Also see the section "Predefined Octet Structure Field Data Types". 

rpcrdefine-octet-structure-field-type-macro name arglist expansion Macro 

Defines an abbreviation for a field type. For example: 

(def ine-octet-structure-f ield-type-macro OSERR () 'integer-16) 

This defines the field-type OSERR to be an abbreviation for the system-defined 
field-type integer-16. 



rpc:define-octet-structure-conversion-field-type name expansion &key (.-conversion 
'identity^ (:result-type 'tj Macro 

Defines a field type that is built on another with just a final data conversion, such 
as a sign extension or bit reversal. 

Here's an example from the system: 

(def i ne-octet-structure-conversi on-f i el d-type fixed-point-16 i nteger-1 6 
iconversion fixed-point-16) 

(defun fixed-point-16 (word) 

(* (Idb (byte 16 0) word) (scale-float 1.0 -16))) 

(defun un-f ixed-point (float) 
(round (ash float 16))) 

(def ine-setf-method fixed-point-16 (ref) 
(let ((store (gensym))) 

(values nil nil (list store) '(setf , ref (un-f ixed-point , store)) ref))) 

The fixed-point-16 field is used to store a fractional number between and 1. To 
make this convenient to manipulate in Lisp, we would want to be able to pass Lisp 
floating-point numbers as arguments, and have the accessor convert the float to a 
16-bit integer to store in the slot. The previous example accomplishes this. 



Predefined Octet Structure Field Data Types 
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Atomic field types 

When defining octet-structures it is often useful to define a new field type in 
terms of some conversion routine, or some expansion, of a previously defined type. 
Although most of the MacOS types are already defined as octet-structure field 
types, the following is a short list of the basic field types: those which are most 
useful when defining your own octet structures and octet-structure field types. 

unsigned-byte (&optional (size 8)) 

signed-byte {size &) 

integer-32 Equivalent to (signed-byte 32). 

cardinal-32 Equivalent to (unsigned-byte 32). 

integer-16 Equivalent to (signed-byte 16). 

cardinal-16 Equivalent to (unsigned-byte 16). 

integer-8 Equivalent to (signed-byte 8). 

cardinal-8 Equivalent to (unsigned-byte 8). 

padding (base-type &optional (repeat 1)) 

Just occupies space; the field cannot be accessed, base-type can 
be any field type. 

vector {type length) length 

Can be a form that references earlier structure elements (such 
as repeat byte count). Referencing returns a vector of the ele- 
ments, or you can use the octet-structure-field-elements loop 
iteration path. 

load-byte {base-type position size) 

Accesses a subfield of base-type access. Useful with *. 

bit {base-type bit-number) 

Equivalent to (load-byte base-type bit-number 1). 

boolean {base-type) Equivalent to base-type with not-temp test. 

boolean-bit {base-type bit-number) 

Equivalent to (boolean (bit base-type bit-number)). 

member {base-type set) 

set is a form to evaluate to a sequence indexed by field. 

subset {base-type keywords) 

One bit for each position to indicate the presence of corre- 
sponding element. 

character-8 () Equivalent to unsigned-8 with code-char input and char-code 

output. 
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ascii-character-8 () Equivalent to unsigned-8 with ASCII-char input and char-ASCII 
output. 



Octet Structure Accessor Forms 

rpc:octet-structure-field-ref (structure-name field-name array index) 
References a field. 

rpc:octet-structure-field-index (reference) 

Returns index in array of start of this field, reference is of the 
form (conc'ed-name array index). 

rpc:octet-structure-field-size (reference) 

Returns size of this field in bytes. 

rpc:octet-structure-total-size (reference) 

Returns size of whole structure in bytes; that is, the index af- 
ter the last field, reference is of the form (structure-accessor 
array index). 

rpc:octet-structure-field-entry (reference) 

References a field pointed to directly by the index, rather than 
to the head of the whole structure. 

rpc:with-octet-structure-access-type (type &body body) 

Overrides the default referencing mode, for using the same 
definition for more than one data representation (such as Sym- 
bolics C and foreign system binary files). 

rpc:with-octet-structure-fields ((structure-name &rest reference-args) fields &body 
body) 

Binds lexical variables to structure slots. Elements of fields ei- 
ther a symbol or a list of local variable and field name. 

loop iteration over octet-structure-field-eiements 

loop for index being the rpc:octet-structure-field-elements of reference Map index 
over the the successive elements of a vector field. Presumably the field type is an- 
other structure type, whose accessors you then use to process each element. 



Octet Structure Field Operations 

rpc:copy-octet-structure (to-reference from-reference) 

Replaces the contents of the octet-structure referred to by to- 
reference with the contents of from-reference. 

rpc:octet-structure-equal (reference-1 reference-2) 

Does a byte by byte comparison of the octet-structures referred 
to by reference-1 and reference-2. 
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Octet Structure Flavor and Structure Synchronization 

rpc:define-octet-structure-and-flavor (structure-name inherit-from &body fields) 

Defines a flavor and structure that parallel one another. The 
flavor has instance variables with same names as field ele- 
ments. 

rpc:copy-fields-from-octet-structure {instance array index) 

Copies from the array into the instance, and returns the index 
past the end of the structure. Uses appropriate method combi- 
nation to get inherit- from' s, fields too. 



Octet Structure Debugging 

rpc:describe-octet-structure {structure-name array index) 

Describes the contents of each field in the octet-structure ref- 
erenced by structure-name array and index. 



Maclvory Extensions to the Macintosh Toolbox 
Window Structures 

mtb:_windowstructure window-pointer window Function 

Returns the contents of the window structure pointed to by the Macintosh pointer 
window-pointer in the Lisp structure cwindow. It is particularly useful when trying 
to examine the state a Macintosh window from Lisp. The window argument is 
overwritten to contain the new information and returned. 

mtb:_cwindowstructure cwindow-pointer cwindow Function 

Returns the contents of the color window structure pointed to by cwindow-pointer 
in the Lisp structure cwindow. Like mtb:_windowstructure, it is useful for exam- 
ining the state of Macintosh windows, and overwrites and returns the argument 
cwindow. 

Access to Macintosh l\/!emory 

mtb:_write-opaque-bytes-into-pointer ptr nbytes buffer Function 

Writes the first nbytes of buffer into the Macintosh memory at the location speci- 
fied by ptr. Ptr should be a Macintosh pointer (as returned by _newptr), buffer 
should be an 8-bit array. Memory on the Macintosh should be allocated prior to 
calling this function. 
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mtb:_read-opaque-bytes-from-pointer ptr nbytes buffer Function 

Reads nbytes from the Macintosh memory pointed to by ptr into the Lisp array des- 
ignated by buffer. The argument buffer is overwritten and returned. 



mtb:_write-opaque-bytes-into-handle h nbytes buffer Function 

Writes the first nbytes of buffer into the Macintosh memory at the location speci- 
fied by h. The memory on the Macintosh should be allocated prior to calling this 
function. 



mtb:_read-opaque-bytes-from-handle h nbytes buffer Function 

Reads nbytes from the Macintosh memory pointed to by h into the Lisp array des- 
ignated by buffer. The argument buffer is overwritten and returned. 

Miscellaneous 



intb:_copybits srcbits dstbits srcrect dstrect mode maskrgn &key :transport-agent 

Function 



intb:_drawpixinap srcbits srcrect dstrect mode maskrgn Function 

Draws the pixMap srcbits on the current GrafPort's portBits. Other arguments are 
as for mtb:_copybits. 



intb:_fsread-reinote refnum into len Function 

On the Macintosh side, reads len bytes from the file open on Macintosh refnum 
refnum, into the Macintosh storage at the Ptr into. 



intb:_fswrite-reinote refnum from len Function 

On the Macintosh side, writes len bytes from the Ptr from into the file open on 
Macintosh refnum refnum. 



intb:_ptrfroinhandle h Function 

Given a handle h, returns the pointer to the contents of the handle. As with all 
handle dereferencing on the Macintosh, you should lock the handle before retriev- 
ing the pointer to its contents and be sure to unlock the handle as soon as possi- 
ble to keep memory from becoming fragmented. 



intb:_setcursorfroinhandle crsrhandle Function 
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Performs a Setcursor on the result. This function is provided as a convenience be- 
cause cursors are usually stored as resources that are accessed by handles. 



intb:_unpackbitsbyrows srcptrin dstptrin rowbytes nrows Function 

Calls UnpackBits starting with srcptrin, dstptrin, and rowbytes, for nrows times. 
Returns two values, the final values taken on by the src and dst Ptrs. 



Maclvory Toolbox Macros 

mtb:cconstant-case test-object &body clauses Macro 

Provides a case statement with keys that are determined by looking up the value 
of the Macintosh constant. Like case, mtb:cconstant-case allows an otherwise 
clause. Here is a simple example: 

(defun my-stdrect (graphic-operation rect) 
(cconstant-case graphic-operation 
(frame (my-f rame-rect rect)) 
(paint (my-paint-rect rect)) 
(erase (my-erase-rect rect)) 
(invert (my-invert-rect rect)) 
(fill (my-fill-rect rect)))) 

Note that frame, paint, erase, invert, and fill are defined as constants on the 
Macintosh (see Inside Macintosh, volume I), and are exported from the mtb pack- 
age in Genera. 

mtb:cconstant-ecase test-object &body clauses Macro 

Like mtb:cconstant-case, but signals an appropriate error if none of the constants 
match test-object. See the macro mtbrcconstant-case for further information. 

mtb:with-qd-port (new-port) &body body Macro 

Saves the current Quickdraw port, as found by calling mtb:_getport, executes the 
body with the current port set to new-port, and restores the original port when 
completed. This is convenient for doing output to Macintosh windows. 

mtbrwith-handle-locked (handle &optional (lock 'i)) &body body Macro 

Executes body with handle locked. You can also pass in a computed boolean, which 
if false means don't bother to lock. Macintosh handles must be locked before they 
can be dereferenced. This prevents the Macintosh memory-manager from relocating 
the memory referred to by the handle. 

See Inside Macintosh, volume II, for more information on memory management. 
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mtbrwith-resource-handle (var restype resid-or-name &key dock :file :sole-file (:di- 
rection :ioJJ &body body Macro 

Causes the Macintosh to read a specified resource by calling _getresource or a 
similar function on restype and resid-or-name. It binds a Lisp var to the handle to 
that resource, resid-or-name is an integer resource-id or string, and is used to find 
the resource. 

If :lock is non-nil the resource is locked around the body. If :file is provided, it is 
opened and used as a resource file around the body. If :sole-file is provided, 
mtbrwith-resource-handle looks only within that file for the resource. The rsole- 
file keyword takes a file reference number (use this instead of a pathname if the 
file is already open). 

Values for rdirection are rinput, routput, or :io; :io is the default and is synony- 
mous with routput. rinput means open the file in read-only mode. 



mtbrwith-resource (var restype resid-or-name &key slock :file :sole-file (.-direction 
rioJJ &body body Macro 

Similar in function to mtbrwith-resource-handle, but copies the resource contents 
to Lisp and binds the Lisp variable to the structure. This is useful for writing 
Lisp programs that read or modify Macintosh resources. 

See the macro mtbrwith-resource-handle for further information. 



mtbrwith-mac-struct (lisp-var octet-structure-type &rest options &key .-handle :ptr) 
&body body Macro 

Copies a structure from the Macintosh system and binds a Lisp variable to it. 

Octet-structure-type (not evaluated) determines the structure type. You provide the 
location of the structure on the Macintosh by specifying either rptr or rhandle. 
When the structure type is specified as nil, raw bytes, are copied, with size deter- 
mined from the size of the object on the Macintosh side. This macro is useful for 
writing Lisp programs that manipulate Macintosh data structures. 



mtbrwith-mac-temp (lisp-var &rest options &key .-handle :ptr .size .-initial-contents) 
&body body Macro 

Allocates a data structure on the Macintosh for the duration of body, binding a 
Lisp variable to its Ptr or Handle. Its size is 0, or size, or length of rinitial- 
contents, which is downloaded into the handle or ptr. The memory is allocated on 
the Macintosh and deallocated on exiting the body. Unlike mtbrwith-mac-struct, 
mtbrwith-mac-temp does not copy the contents of the Macintosh memory to the 
Lisp side. 



mtbrwith-resload (new) &body body Macro 
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Binds the state of ResLoad to new, restoring the old state on exiting the body. 



mtbrusing-resfile (refnum) &body body Macro 

Uses mtb:_useresfile of refnum around the body, restoring the previous value of 
currentresf ile on exit. 



mtbrwith-resfiles ((var name &optional direction) ...) Macro 

Opens one or more resource files for body, binding Lisp variables to their refnums. 
Direction is rinput (the default), or one of the synonyms routput or :io. The re- 
source files are closed on exit. 



mtbrdo-restypes (type-var refnum-or-all) &body body Macro 

Iterates over all resource types in one resource file, specified by refnum-or-all, 
binding type-var to each type. When refnum-or-all is rail, mtbrdo-restypes iterates 
over all types in all open resource files. 



mtbrdo-rsrcs (handle-var id-var name-var) (restype refnum-or-all &key :load) &body 
body Macro 

Iterates over resources of a given type, receiving a resource handle, id, and name. 
refnum-or-all is as in mtbrdo-restypes. When rload is t, mtbrdo-rsrcs loads each 
resource. 



mtbrmap-over-mac-queue-elements (element-var octet-structure-type queue-hdr- 
pointer) &body body Macro 

Executes body once for every element in a Macintosh system queue. On each itera- 
tion element-var is bound to a Lisp octet-structure of type octet-structure-type con- 
taining a copy of the Macintosh queue-element. 

queue-hdr-pointer is the pointer to the queue-hdr structure in Macintosh memory 
(as returned by mtbr_getvcbqhdr, for example). This macro is useful for mapping 
over the Macintosh operating system queues, such as the vcb queue, the drive 
queue, or the vertical retrace queue. 



mtbrwith-open-refnum (var pathn &key :vrefnum :dirid .-permission sresource-fork) 
&body body Macro 

Opens the host file named by the Lisp pathname pathn for the duration of body, 
binding var to the resulting refnum. Used when a MacOS refnum is needed in- 
stead of a Lisp stream (in contrast to with-open-file). The rpermission, rdirid, and 
rvrefnum arguments are passed to the Macintosh File Manager (mtbr_phbopen) to 
open the file. If rresource-fork (default nil) is true, a stream to the file's resource 
fork is opened instead of the data fork. (PBHOpenRF vs. PBHOpen). If a Macin- 
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tosh operating system error occurs while attempting to open the file, an appropri- 
ate Lisp condition is signaled. 



mtbrwith-pict-from-file (handle-var rect &key pathname refnum (temporary T) 
&body body Macro 

Allocates a Macintosh handle to receive the contents of a PICT file, reads the file 
into the handle, and binds handle-var to the pict handle and rect to its picframe, 
for the duration of body. Specify the file with the Lisp pathname pathname, or pro- 
vide an already open MacOS refnum in refnum. If you specify rtemporary nil, the 
Macintosh handle is not deallocated at the end of body. 



mtbrshow-resfiles Function 

Shows the linked list of open MacOS resource files, offering the refnum and file 
name. It attempts to mark the current resource file with "*^". 



mtbrez-sfgetfile &key x-and-y types Function 

Interface to mtb:_sfgetfile. x-and-y is a list (x y) or a Point, defaulting to 100,100. 
types determines what types of files are offered by SFGetFile. Returns three val- 
ues: vrefnum, fname (string), and ftype (string). If no rtypes argument is supplied, 
then any file type is allowed. 



mtbroctet-ref-remote-ptr (octet-structure-field-accessor ptr &optional offset) Macro 

Remotely performs the specified octet structure field access by reading just the 
necessary bytes from the Macintosh location specified by ptr and offset, setf can be 
used with mtbroctet-ref-remote-ptr expressions. 

Examples: 

• The common operation of finding the QuickDraw port rectangle of a Macintosh 
window can be done with: 

(octet-ref-remote-ptr (grafport-portrect (_f rontwindow)) 

This is equivalent to, but faster than, transferring the entire window structure 
into Lisp: 

(with-mac-struct (window windowrecord :ptr (_f rontwindow)) 
(grafport-portrect window 0)) 

• You could increment the refcon of a Macintosh window with: 

(incf (octet-ref-remote-ptr (windowrecord-refcon mac-window))) 

• To move the bounds rectangle for a dialog template whose Macintosh ptr is in 
the Lisp variable the-templ ate, you can use: 
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(setf (octet-ref-remote-ptr 

(di al ogtempl ate-boundsrect the-templ ate) ) 
(_offsetrect (octet-ref-remote-ptr 

(dial ogtempl ate-boundsrect the-templ ate)) 10 0)) 



mtbroctet-ref-remote-handle (octet-structure-field-accessor handle &optional offset) 

Macro 

Like mtbroctet-ref-remote-ptr, except this is applied to a handle. The handle is 
locked around the access, offset applies to the dereferenced handle, setf can be 
used with mtbroctet-ref-remote-handle forms. 

For example, given a ptr to a Macintosh window, you could collect a list of all of 
its controls with their refcons: 

(loop for control = (octet-ref-remote-ptr 

(windowrecord-control 1 ist mac-window)) 
then (octet-ref-remote-handle 

(control record-nextcontrol control ) ) 
until (zerop control) 
collect (let ((refcon (octet-ref-remote-handle 

(control record-contrl rf con control ) ) ) ) 
(list control refcon))) 



mtbrwrite-remote-number &key byte word long ptr handle offset Function 

Writes the specified byte, word, or long into the specified Macintosh ptr or handle, 
at a location offset by offset if supplied. Useful for callbacks altering Pascal var 
parameters. 



mtb:with-rect (var &optional left top right bottom) &body body Macro 

Binds var to a data-stack Rect for the duration of body. Unspecified edges default 
to zero. Useful when dealing with Macintosh toolbox routines. 

For example, one could draw a wide rectangle on the current GrafPort with 

(with-rect (r 10 10 100 30) (_framerect r)) 

As another example, one could move a dialog item with this: 

(with-rect (r) 

(multiple-value-bind (item-type item-handle) 
(_getditem the-dialog item-number r) 
(_offsetrect r 20 0) 
(_setditem the-dialog item-number item-type item-handle r))) 
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mtbrwith-point (var x y) &body body Macro 

Binds var to a data-stack Point for the duration of body. Useful when dealing with 
Macintosh toolbox routines. 



mtbrdescribe-eventrecord event-record Function 

Describes an octet-structure containing an EventRecord, decoding the event kind, 
mouse button state. Prints to *standard-output*. Probably useful only for debug- 
ging. 



mtbrwith-temps (&rest var-creator-destructor-triples) &body body Macro 

Binds one or more Lisp variables to freshly created entities, for the duration of 
body, destroying them (if non-null) when body terminates. The advantage of this 
over unwind-protect is that it places the creator and destroyer syntactically adja- 
cent. Each creator is a function applied to no arguments (that is, mtbrwith-temps 
wraps a set of parentheses around it); each destructor is a function applied to the 
corresponding var. 

(with-temps ((update-region _newrgn _disposergn) 

(ptr (lambda () (_newptr size)) _disposptr)) 

— ) 



mtb:mac-pathname-from-parts vrefnum dirid name Function 

Given pieces of a Macintosh pathname, constructs a Lisp pathname. Recursively 
looks up names of parent folders until reaching the file system root. 

Example: 

(defun std-f ile-accept-pathname () 

(multiple-value-bind (vrefnum name type) 

(mtb:ez-sfgetfile :types '("TEXT" "PICT")) 
(values (mtb: :mac-pathname-f rom-parts vrefnum name) type))) 



mtb:with-mac-file-struct (var octet-structure-type filepos refnum) &body body Macro 

Binds var to an octet structure of the named type read at filepos from the Macin- 
tosh file open on refnum. 

Example: 
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(defun size-of-pict-in-pict-f ile (pathname) 
(declare (values width height)) 

(mtb:with-open-refnum (in pathname :permission (mtbicconstant fsRdPerm)) 
(mtb: :with-mac-f ile-struct (pict mtb::picture 512 in) 
(let ((rect (mtb:picture-picf name pict 0))) 

(values (- (mtb: rect-right rect 0) (mtb: rect-left rect 0)) 

(- (mtb: rect-bottom rect 0) (mtb: rect-top rect 0))))))) 



mtbrwith-mac-file-bytes (var len filepos refnum) &body body Macro 

Binds var to an octet vector of length len, read at filepos from the Macintosh file 
open on refnum. 



mtb: do-mac- volumes (volume-name volume-refnum &optional volumeparam) &body 
body Macro 

Iterates over all mounted MacFS volume structures. Body receives the volume- 
name string (without trailing colon), that volume's refnum, and, if needed, a Vol- 
umeParam structure. The string containing the volume name, and the Vol- 
umeParam structure, are allocated on the data stack, so they must be copied if 
they are to be used later. 

Example: 

(mtb: : do-mac-volumes (name refnum) (print (list name refnum))) ==> 
("Mac-4" -1) 
("DSK" -2) 
("SneakerNet Packet Floppy" -3) 



mtb:with-one-mac-rsrc (var pathname rsrc-type &key :rsrc-id :rsrc-name (:vrefnum 
0) (:dirid 0)) &body body Macro 

Finds a resource of type rsrc-type, id :rsrc-id, or name :rsrc-name in the Macin- 
tosh file pathname (adjusted by vrefnum and dirid), moves it to the Lisp side, and 
binds var to it. mtb:with-one-mac-rsrc also decodes the resource file. For resource 
files with large resource maps, this offers increased performance over using 
mtb :with-resf lies or mtbrwith-resource :sole-file with Macintosh's Resource Man- 
ager. 

For related information, see "The Resource Manager is not a database." - Macin- 
tosh Technical Note #203: Don't Abuse the Managers, August 1, 1988. 



mtb:_debugger &key :transport-agent Function 

Enters the Macintosh debugger (Macsbug, for example), after halting the Macin- 
tosh at an instruction in the RFC remote entry. 
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intb:_debugstr string &key :transport-agent Function 

Enters the Macintosh debugger (Macsbug, for example), after halting the Macin- 
tosh at an instruction in the RPC remote entry, passing it string to print as part 
of its greeting. 



mtbrusing-scratch-resfile () &body body Macro 

Runs body using a scratch resource file as the current resource file. The scratch 
file is deleted when you quit the Genera icon. 



mtbrdownload-resource res-type res-name res-id res-attr data Function 

Creates a Macintosh resource in a scratch resource file. The first four arguments 
define the resource, data is the contents of the resource, mtbrdownload-resource 
returns two values: a handle and res-id. When you specify nil as res-id's value, 
mtbrdownload-resource generates a unique id for the resource. 



Callbacks 

A callback is a piece of user code whose address is given to MacOS to be called by 
MacOS at some later time to perform some specific function defined by MacOS. 
Examples of callbacks are: custom QuickDraw QDProcs, an actionProc passed to 
TrackControl, or a filterProc passed to ModalDialog. The interfaces described here 
can construct temporary Macintosh routines (essentially closures on the Macintosh 
side) to serve as "trampolines" to pass callback args to Lisp, and to receive Lisp's 
values to pass back to MacOS. A more complete technical description of the imple- 
mentation appears in "Callback Mechanism" . Because each kind of callback takes 
different arguments and returns different values (or no values), we use callback 
types, which are symbolically named. 

In general, callbacks are useful only in the context of a remote-program. Each call- 
back call is processed in a new process spawned by the RPC machinery. 

Callbacks receive args from MacOS, and can return values if MacOS specifies 
them as functions. Pascal var parameters, passed to callbacks as Ptrs, can be al- 
tered with mtbrwrite-remote-number. 

The callback constructor functions in the mtb package return a Macintosh ProcP- 
tr, represented in Lisp as a fixnum. Such an address is ready to be installed into 
Macintosh data structures, passed back to some Macintosh Toolbox routine, or 
whatever else is required by the application. 

Each callback establishes a unique association with the specified Lisp code. This 
admits many co-extant callbacks of the same type without conflict or confusion. 



mtbrwith-mac-callback (var callback-type &key program) ((handler-args) &body 
handler-body) &body body Macro 
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For the duration of body, binds var to the Macintosh address for a callback of type 
callback-type. When the callback is called, bind handler-args to its args, and run 
handler-body in its own process. The callback's return value (if needed) is the val- 
ue of handler-body, program is a remote program, defaulting to dw:*prograin*. Al- 
though handler-body is run in another process, it does, of course, share the lexical 
environment in which it appears. 



mtbrwith-mac-callback-function (var callback-type function &key program) Macro 

For the duration of body, binds var to the Macintosh address for a callback of type 
callback-type. When the callback is called, apply function the callback's args. The 
callback's return value (if needed) is the value returned by function, program is a 
remote-program, defaulting to dw:*prograin*. 



mtbrmake-inac-callback callback-type function program Function 

Constructs a callback "closure" on the Macintosh side, of callback-type 
callback-type, which when called will call the Lisp function in the context of the re- 
mote program program. Returns the Macintosh address of the callback This is un- 
done by mtb:remove-mac-callback. 



mtbrremove-inac-callback mac-callback Function 

Deallocates the callback addressed by mac-callback and removes the Lisp data 
structures establishing the correspondence with the Lisp function. 



Callback Types 

This section describes the arguments and values for each callback type, along with 
associated C types. Call-by-reference parameters (Pascal var parameters) are noted 
with C syntax. 



mtbrcontrol-definition Callback 

Arguments: 

varcode short 
thecontrol Control Handle 
message short 
param 1 ong 
Values: 

result 1 ong 

Custom control defintion. See Inside Macintosh, page 1-329. Because of the Mac- 
intosh's Control Manager design, you will have to adjust CDEF resources before 
you can actually get one of these called. 
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mtbrcontrol-indicator-action Callback 

Arguments: none 
Values: none 

A control's action procedure for when the mouse was pressed in an indicator. See 
Inside Macintosh, page 1-324. Suitable for passing to _TrackControl or _SetCtlAc- 
tion. 



mtbrcontrol-nonindicator-action Callback 

Arguments: 

thecontrol Control Handle 

partcode short 
Values: none 

A control's action procedure for when the mouse was pressed in some control oth- 
er than an indicator. See Inside Macintosh, page 1-324. Suitable for passing to 
mtb:_trackcontrol or mtb:_setctlaction. 



mtb:dialog-sound-proc Callback 

Arguments: 

soundno short 
Values: none 

Emits alert sounds. See Inside Macintosh, page 1-409. 



mtb:dialog-user-item-definition Callback 

Arguments: 

thewindow WindowPtr 

itemno short 
Values: none 

Draws userltems in dialogs. See Inside Macintosh, page 1-421-2 and 1-431. 



mtbrmenu-definition Callback 

Arguments: 

message short 

themenu MenuHandle 

menurect Rect* 

hitpt Point* 

whichitem short* 
Values: none 
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Implements custom menus. See Inside Macintosh, page 1-362. Because of the Mac- 
intosh's Menu Manager design, you must use MDEF resources to get one of these 
to be called. 



mtbrmodal-dialog-filter Callback 

Arguments: 

thedialog DialogPtr 

theevent EventRecord* 

itemhit short* 
Values: 

result Bool ean 

Preprocesses events for ModalDialog. See Inside Macintosh, page 1-415. 



mtbrquickdraw-arcproc Callback 

Arguments: 

verb GrafUerb 

r Rect* 

startangle short 

arcangle short 
Values: none 

Customizes QuickDraw arc/wedge drawing. See Inside Macintosh, page I-197ff. 
mtbrquickdraw-bitsproc Callback 



Arguments: 




srcbits 


BitMap* 


srcrect 


Rect* 


dstrect 


Rect* 


mode < 


short 


maskrgn 


RgnHandle 


Values: none 





Customizes QuickDraw bit transfer. See Inside Macintosh, page I-197ff. 



mtb : quickdr aw-commentproc Callback 

Arguments: 

kind short 

datasize short 

datahandle Handle 
Values: none 
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Customizes QuickDraw picture comment processing. See Inside Macintosh, page 
I-197ff. 



mtb : quickdr aw-getpicproc Callback 

Arguments: 

dataptr Ptr 

bytecount short 
Values: none 

Customizes QuickDraw picture retrieval. See Inside Macintosh, page I-197ff. 



mtb: quickdr aw-lineproc Callback 

Arguments: 

newpt Point* 
Values: none 

Customizes QuickDraw line drawing. See Inside Macintosh, page I-197ff. 



mtb: quickdr aw-ovalproc Callback 

Arguments: 

verb GrafUerb 

r Rect* 
Values: none 

Customizes QuickDraw oval drawing. See Inside Macintosh, page I-197ff. 



mtb: quickdr aw-polyproc Callback 

Arguments: 

verb GrafUerb 

poly PolyHandle 
Values: none 

Customizes QuickDraw polygon drawing. See Inside Macintosh, page I-197ff. 



mtb : quickdr aw-putpicproc Callback 

Arguments: 

dataptr Ptr 

bytecount short 
Values: none 
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Customizes QuickDraw picture saving. See Inside Macintosh, page I-197ff. 



mtbrquickdraw-rectproc Callback 

Arguments: 

verb GrafUerb 

r Rect* 
Values: none 

Customizes QuickDraw rectangle drawing. See Inside Macintosh, page I-197ff. 



mtbrquickdraw-rgnproc Callback 

Arguments: 

verb GrafUerb 

rgn RgnHandle 
Values: none 

Customizes QuickDraw region drawing. See Inside Macintosh, page I-197ff. 



mtbrquickdraw-rrectproc Callback 

Arguments: 

verb GrafUerb 

r Rect* 

ovalwidth short 

ovalheight short 
Values: none 

Customizes QuickDraw roundRect drawing. See Inside Macintosh, page I-197ff. 



mtbrquickdraw-textproc Callback 

Arguments: 

bytecount short 

textbuf Ptr 

numer Point* 

denom Point* 
Values: none 

Customizes QuickDraw text drawing. See Inside Macintosh, page I-197ff. 
mtbrquickdraw-txmeasproc Callback 
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Arguments: 

bytecount short 

textaddr Ptr 

numer Point* 

denom Point* 

info Fontlnfo* 
Values: 

width short 

Customizes QuickDraw text width measurement. See Inside Macintosh, page 
I-197ff. 



mtb:standard-file-dialog-hook Callback 

Arguments: 

item short 

thedialog DialogPtr 
Values: 

result short 

Customizes StandardFile dialogs. See Inside Macintosh, page 522. 



mtb : standard-file-file-filter Callback 

Arguments: 

paramblock ParmBlkPtr 
Values: 

result Bool ean 

Filters out file types for StandardFile dialogs. See Inside Macintosh, page 1-524. 



mtbrtext-edit-click-proc Callback 

Arguments: none 
Values: 

result Bool ean 

Customizes TextEdit clikLoop. See Inside Macintosh, page 1-390. 



mtb:text-edit-word-break-proc Callback 

Arguments: 

text Ptr 

charpos short 
Values: 

result Bool ean 
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Customizes TextEdit word break computation. See Inside Macintosh, page 1-390. 



mtbrwindow-definition 

Arguments: 

varcode short 

thewindow WindowPtr 

message short 

param 1 ong 
Values: 

result 1 ong 

Implements custom windows. See Inside Macintosh, page 1-299. 



Callback 



mtbrget-canned-callback canned-callback-type 



Function 



Returns the Macintosh address of a simple, parameterless callback. Some callbacks 
are so simple that they can be written in C, to run entirely on the Macintosh side, 
instead of communicating back to the Lisp side. At present, there is only one 
canned callback type, mtb:draw-dialog-line. 



Callback Mechanism 

This section briefly describes how the callback mechanism is implemented. 
The call chain when MacOS calls a callback is this: 

mac-closure 
-^ C-client remote entry 
-^ Lisp-server remote entry 
-^ Lisp callback function 

Here mac-closure is a sequence of M68000 machine instructions constructed by 
Lisp and sent over to the Macintosh, containing as immediate data five variable 
fields: a closure id, application id, value to load register A4 with, the address of 
the C-client remote entry, and the number of bytes of arguments to clear off the 
stack. Here is the assembly code. The variable fields to be filled in by Lisp are 
marked in bold. 

link a6,tt-4 
move.l a4,-(sp) 
movea . 1 tta4value, a4 



;; push C args, right to left 
pea -4(a6) 
pea 8(a6) 
pea appljd 
pea closurejd 



;location for return value, if needed 
;addr of last (Pascal) arg 
;application unique-id 
iclosure code (not address..) 
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jsr Htfxxxx ;call the RPC remote entry 

lea 16(a7),a7 ;C caller must remove args 

;; Fail to check DO for RPC errors -- what could we do anyway? 
move.l -4(a6),d0 ;return value 

move.l (sp)+,a4 ;restore old A4 

unlk a6 

movea.l (a7)+,a0 ;return addr 

lea argsize(a7) ,a7 ;Pascal callee must remove args 

move.l d0,(a7) ;return value 

jmp (a0) ;return 

Each callback type has a C-client remote entry. Its arguments are closure-id, appli- 
cation-id, and an anonymous struct* argument representing its caller's arglist. 
That remote entry passes closure-id, application-id, and each arg of the caller's ar- 
glist, across the RPC mechanism to the Lisp-server side. 

There is also a C-server remote entry that receives a callback-type index from 
Lisp-client; it returns to Lisp two longs, the Macintosh address of the specified 
C-client remote entry of the previous paragraph, and the current value of register 

A4. 

All C-side remote entries of the previous two paragraphs are linked into a single 
code resource of RPC module type autoload-with-static-data, locked in Macintosh 
memory when loaded. Because this is an autoload code resource, it needs a correct 
value in register A4 to refer to its globals. Actually, the only global is DefaultXDRA- 
gent, needed by the C-client remote entries. Defaul tXDRAgent is filled in by the 
callback-address-returning C-server remote entry. 

All the Lisp-server sides of the callback remote entries have similar bodies. Each 
body will use the application-id to locate the appropriate remote program, and the 
closure-id to locate the appropriate Lisp function to call back. Then it applies the 
Lisp function to the reverse of the vector of RPC arguments received from the 
Macintosh side. It has to reverse the vector because the Pascal calling sequence 
(used by the caller of the callback in the first place) pushes the arguments left-to- 
right on a stack which grows toward lower addresses. Thus, the last Pascal argu- 
ment appears first in memory. 



Examples of Developing Maclvory User Interfaces 

You can find several examples of code that creates Maclvory user interfaces in the 
directory syS:EMBEDDING;MACIvory;TOOLbox;EXAMples;. These examples are printed in 
the appendix "Maclvory User Interface Examples". They include etest.lisp, pic- 
show.lisp, menubar.lisp, and show-icons.lisp. 

Etest and Pic-show are remote programs. To run them, use the unassigned Genera 
application icon in the Macintosh Applications folder. Copy the icon and then name 
it with the name of the remote program. Opening the icon runs the program. (You 
can also use the Configure Maclvory Application command as an alternative to this 
procedure). 
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The following list describes each program: 

• etest.lisp, which defines remote program "ETest" with three menu commands: 

° Test-1 (clover-S), which draws a solid black circle. You can use the scroll bars, 
and reshape the window. 

° Splash (clover-F), which draws the Bear»Cal splash window. It reads Macin- 
tosh PICT contents from the sys host, ships it over to the Mac, writes it into 
a new pict, and draws that pict when the window's displayer wants it. 

° Dialog (clover-D), which creates a modal dialog for an airline reservation sys- 
tem (Bear'Cal). It shows how to use the dialog functionality. 

credit-card-picts.rsrc and splash.pict are binary data files used by the ETest 
commands, splash.pict is taken from the sys host, so you can try it out without 
further work. To use the credit-card-picts.rsrc demo, you must copy it onto your 
Macintosh before running the Dialog demo, and then edit a defvar in etest to 
say where the file has been copied. 

• pic-show.lisp, which contains an application that browses for Macintosh files 
containing pictures, and lets you see them. You can use scrolling and zooming 
with these windows. 

• menubar.lisp, which demos advanced octet-structure definitions and usage, us- 
ing the Macintosh menu bar as an example. 

• show-icons.lisp, which uses toolbox macros and generic graphics substrate to 
show you all the icons and mouse cursors in the system file. 



Launching Macintosh Applications 

The following functions are provided for launching Macintosh applications from 
Genera: 



mtb:_launch name fdflags launchflags &key :transport-agent Function 

Launches the application in the file named by name, using fdflags and launchFlags. 

Because of limitations of Macintosh's _launch, most Maclvory users will want to 
use mtb:launch-mac-application, which is more comprehensive, instead of the 
mtb:_launch function. See the Apple Macintosh documentation on launching appli- 
cations for further information. 



mtb:launch-mac-application application-pathname &rest document-pathnames 

Function 
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Launches the Macintosh apphcation in application-pathname, telling it to open the 
documents in document-pathnames. If application-pathname is nil, locates the re- 
sponsible application by looking up the file types of document-pathnames in the 
Finder's desktop file. 

The returned value is a Macintosh process-id, used, for example, to inform a shell 
that a child has died. See Macintosh Technical Note #205 for further information 
on this topic. 

Example: 

(mtb : : 1 aunch-mac-appl i cati on 

ttp"HOST :DSK:MacIvory Appl icationsiHyperlvory Stack") 

Notes: If the launch does not succeed for some reason (file not found, not enough 
memory), the error code returned by _launch itself (and signalled by mtbrlaunch- 
mac-application ) does not always appear to be meaningful. 

In Macintosh System 7.0, Apple plans to reimplement the Macintosh software used 
to launch applications. This function may be made obsolete by those changes. 



Hardware-dependent Data Formats 

In using Ivory embedded in standard systems (such as Macintosh) or standard 
busses (such as VMEbus) you sometimes have to deal with hardware that uses da- 
ta formats that differ from Ivory formats; for instance, bits may be numbered in 
the other direction. Symbolics provides hardware that speeds up any bit shuffling 
this may require. 

The bit-shuffling hardware is necessarily different in each system. Also, some sys- 
tems do not need bit shuffling at all (for instance, the IBM PC uses the same data 
formats as Ivory for numbers and strings). The macro sys:with-hardware-bit- 
shuffling provides a general mechanism to cover up all this system-dependent 
complexity. It expands into code that works on all Ivory-based systems, by means 
of dispatches on sys:*system-type. Note that this macro is strictly for accessing 
host hardware. You cannot use it for general purpose bit or byte reversal, such as 
when decoding a file created by a foreign system, because the bit-shuffling hard- 
ware does not work that way. 



sys:with-hardware-bit-shuffling (variable mode) body Macro 

The variable contains a pointer to a block of storage that is to be accessed with bit 
shuffling in effect during the execution of the body. Bit shuffling is per-process 
(actually per-stack-group). The block of storage must be in a portion of address 
space that is capable of using the bit shuffling hardware. In most systems this re- 
quires dtp-physical-address and is not the portion of physical address space that is 
used for storing virtual pages. Thus when doing a bit shuffling block transfer be- 
tween an I/O device and main memory, variable points at the I/O device. If variable 
doesn't meet these requirements, an error is signaled. In some systems, such as 
Maclvory, bit shuffling is (partially) encoded in the address bits; for this reason, a 
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new variable named variable is bound to a potentially modified version of the ad- 
dress in variable; its scope includes body. 

The mode identifies the units of storage to remain intact through the bit shuffling. 
It must evaluate to one of the following keyword symbols: 

bit Single bits, dtp-fixnum tag 

nibble 4 bits at a time, dtp-fixnum tag 

byte 8 bits at a time, dtp-fixnum tag 

fixnum 32 bits at a time, dtp-fixnum tag 

single-float IEEE 32-bit float, dtp-single-float tag 

If the host hardware uses the same data format as the Ivory for these units, no 
shuffling occurs. Otherwise, data words are rearranged as they are read or written 
to translate the formats. For example, :bit mode in Maclvory reverses the order of 
bits in a word, to match Ivory's least-significant-bit-first order to the Macintosh's 
most-significant-bit-first order. 

Enhancing Maclvory Performance 
Using Off-Screen Bitmaps 

Off-Screen Bitmaps 

The Genera window system stores images in bitmaps: two-dimensional arrays of 
bits. Sometimes these are called pixmaps (two-dimensional arrays of pixels), espe- 
cially when there is more than one bit per pixel, as on color screens. Each bitmap 
has a width, a height, and a depth; the depth is the number of bits per pixel. 

A bitmap can be on the screen or off the screen. An on-screen bitmap is stored in 
special memory associated with the display hardware, thus its contents is visible 
on the screen. The image of an exposed window resides in an on-screen bitmap so 
you can see it. 

All other bitmaps are off-screen. The Genera window system often uses an off- 
screen bitmap to save the image of a deexposed window, so that the image can be 
quickly restored when the window is exposed, by copying the off-screen bitmap into 
an on-screen bitmap. This feature is under the control of the individual window, 
through the :save-bits option, however most standard windows enable it. The Gen- 
era window system also uses an off-screen bitmap to save the image underneath a 
temporary window, such as a pop-up menu. User programs can also use off-screen 
bitmaps for their own purposes, using the facilities described below. 

In embedded systems, such as Maclvory, bitmaps have one more degree of free- 
dom: a bitmap can be in Ivory's normal virtual memory, or it can be in host mem- 
ory. On-screen bitmaps are always in host memory, because the host owns the dis- 
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play hardware. This is why the screen-array bitmap of an exposed window general- 
ly cannot be directly accessed by an Ivory program in an embedded system. Similar 
considerations apply to X Windows, substituting X Window Server memory for host 
memory. 

Off-screen bitmaps can be in either Ivory memory or host memory. There are per- 
formance tradeoffs associated with the decision of where to store an off-screen 
bitmap. The principal constraints are the limited speed for copying images between 
Ivory memory and host memory, and the limited size of host memory. 

On the one hand, placing an off-screen bitmap in host memory yields the maxi- 
mum speed when copying images to or from the screen. Making the host Macin- 
tosh solely responsible for the copying is significantly faster than having to coordi- 
nate two processors and copy through the co-processor communications memory. 
You will not see the screen being slowly repainted top to bottom. 

On the other hand, placing an off-screen bitmap in Ivory memory avoids consum- 
ing the limited amount of available host memory. In a minimum-configuration 
Macintosh II, there is only 1 megabyte of host memory, of which about 350 to 400 
kilobytes is available for off-screen bitmaps. In a larger Macintosh II, up to a few 
megabytes might be available, but even that may hold only a few large bitmaps. 
The size of a bitmap depends on the application and on the size and depth of the 
display monitor. 

To avoid severely limiting the number of off-screen bitmaps, Maclvory swaps less 
recently used bitmaps onto the disk to make room in host memory. Of course, 
since swapping to and from the disk takes time, you will benefit from having as 
many bitmaps as possible in memory at once. This is controlled by the amount of 
host memory available to the Genera application. Since the Macintosh does not 
have a flexible multiple-application memory allocation scheme, this is controlled by 
the size set for the Genera application with the Get Info command in the Finder's 
File menu, and limited by the amount of actual memory you have and the number 
of other Macintosh applications you wish to run at the same time. See the section 
"Setting the Size of Application Icons That Use Ivory". 

An additional concern when drawing text or graphics into a bitmap is who does 
the drawing. When the bitmap is in host memory, the Macintosh host processor 
does the drawing, using QuickDraw. When the bitmap is in Ivory memory, the 
Ivory processor does the drawing. Which way is faster depends on the type of 
graphic operation being performed and the hardware configuration. In sketch mode 
(which is the default), the appearance of some graphic shapes varies depending on 
which processor does the drawing. For accurate drawing, you can disable sketch 
mode, but drawing into bitmaps in host memory (whether on-screen or off-screen) 
may then be slower. See the special form graphics:with-scan-conversion-mode. 

These considerations mean the decision of whether to place an off-screen bitmap in 
Ivory memory or in host memory depends on the application and on the hardware 
configuration. The Genera window system decides as follows: Off-screen bitmaps 
for temporary use always go in host memory, unless not enough host memory is 
available even after swapping out other bitmaps. In this case they go in Ivory 
memory. Off-screen bitmaps for deexposed windows go in host memory or Ivory 
memory depending on how much host memory is available. 
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See the variable mtb:*pixmap-correspondence-memory-threshold*. See the vari- 
able mtb:*automatically-generate-pixmap-correspondences*. 



Using Off-Screen Bitmaps in Your Application 

Several interfaces are provided through which your application can use off-screen 
bitmaps. In embedded systems, all of these interfaces can store the off-screen 
bitmaps in host memory. 

If you are presently doing things such as drawing to bit arrays and then bitblting 
to the screen, you should seriously consider using off-screen bitmaps in host mem- 
ory, due to the substantial performance advantage in embedded systems such as 
Maclvory or the UX. 

The available interfaces are: 

tv:with-off-screen-drawing 

tv:with-output-to-bitmap-stream 

tv:with-output-to-bitmap 

tvrallocate-bitmap-stream 

tv:with-temporary-sheet-bit-raster 



Using Off-Screen Bitmaps for Instantaneous Updates 

This simple interface gives the appearance of an instantaneous update, rather than 
of each item appearing to be drawn separately. tv:with-off-screen-drawing works 
by copying the contents of a window to an off-screen bitmap, drawing into the 
bitmap, and copying back. In embedded systems, the off-screen bitmap always re- 
sides in host memory, provided sufficient host memory is available. 

For instance, 

(defun off-screen-strings () 

(tv : wi th-of f -screen-draw i ng (*termi nal -i o*) 
(dotimes (i 15) 

(write-string "12345678901234567890") 
(terpri)))) 

(defun off-screen-graphics () 

(tv : wi th-of f -screen-draw i ng (*termi nal -i o*) 
(graphics: with- room-for-graphics () 
(graphics:draw-circle 100 100 50) 
(graphics:draw-triangle 20 120 70 75 :alu :flip)))) 

This involves some overhead in that you need to allocate and deallocate an off- 
screen bitmap, and copy from the window to the bitmap and back, each time the 
screen is visibly updated. In some cases the copy from the window to the bitmap is 
unnecessary, because the entire contents of the window will be redrawn. The 
rcomplete-redisplay option allows for optimization of this case. For example. 
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(defun off-screen-graphics-2 () 

(tv : wi th-of f -screen-draw i ng (*termi nal -i o* 

:complete-redi splay t) 
(graphics: with- room-for-graphics () 
(graphics:draw-circle 100 100 50) 

(graphics:draw-triangle 20 120 70 75 :alu :flip)) 
(send *terminal-io* : refresh-margins))) 

This is faster, but the previous content of the window is erased, where the previ- 
ous example just scrolled it upwards. 

Using Off-Screen Bitmap Streams 

tv:with-output-to-bitmap-stream is a powerful interface that gives you an off- 
screen bitmap that supports all of the stream output and graphical operations of 
windows. The :host-allowed keyword controls whether the off-screen bitmap is 
stored in host memory or Ivory memory. There is no automatic copying from a 
window to the bitmap and back; you use the rbitblt and :bitblt-to-sheet messages 
to do this if and when you need it. Note that :host-allowed t is ineffective unless 
you also use :for-stream to specify a stream that leads to a screen; otherwise 
tv:with-output-to-bitmap-stream doesn't know which of potentially many hosts to 
use. 

For example, 

(defun off-screen-1 ines-1 (&aux (stream *terminal-io*)) 
(fresh-line stream) 
(multiple-value-bind (ex cy) 

(send stream : visible-cursorpos-1 imits) 
(tv : wi th-output-to-bi tmap-stream (bi tmap-stream 

:for-stream stream 
:host-al lowed t) 
(loop for X below 100 by 10 do 

(send bitmap-stream : clear-window) 
(loop for y downfrom (- 100 x) by 2 repeat 5 do 
(loop for X from x by 2 repeat 5 do 

(send bitmap-stream : draw-line x y))) 
(send bitmap-stream :bitbl t-to-sheet boole-xor 100 100 
stream (+ ex 150) (+ cy 150)))))) 

The previous example used a bitmap the full size of the window. We can improve 
it by creating a bitmap only as large as we need: 

(defun off-screen-1 ines-2 (&aux (stream *terminal-io*)) 
(fresh-line stream) 
(multiple-value-bind (ex cy) 

(send stream : visible-cursorpos-1 imits) 
(tv : wi th-output-to-bi tmap-stream (bi tmap-stream 

:for-stream stream 
:host-al lowed t 
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:width 100 :height 101) 
(loop for X below 100 by 10 do 

(send bitmap-stream : clear-window) 
(loop for y downfrom (- 100 x) by 2 repeat 5 do 
(loop for X from x by 2 repeat 5 do 

(send bitmap-stream : draw-line x y))) 
(send bitmap-stream :bitbl t-to-sheet boole-xor 100 100 
stream (+ ex 150) (+ cy 150)))))) 

If you specify values for rwidth and rheight that are too small, the bitmap auto- 
matically expands so it is at least large enough to hold all the bits drawn. Of 
course the expansion takes time, so it is preferable to specify accurate values for 
rwidth and rheight. 

We can further improve the speed by using rdraw-multiple-hnes in place of 
rdraw-hne, to cut down on overhead. It speeds up this particular example by only 
7 percent since the line-drawing speed of the Macintosh is the limiting factor in 
either case. 

(defun off-screen-1 ines-2-m (&aux (stream *terminal-io*)) 
(fresh-line stream) 
(multiple-value-bind (ex cy) 

(send stream : visible-cursorpos-1 imits) 
(tv : wi th-output-to-bi tmap-stream (bi tmap-stream 

:for-stream stream 
host-allowed t 
width 100 :height 101) 

(loop for X below 100 by 10 do 

(send bitmap-stream : clear-window) 
(send bitmap-stream :draw-mul tiple-1 ines 

(loop for y downfrom (- 100 x) by 2 repeat 5 
nconc 

(loop for X from x by 2 repeat 5 
collect X collect 
collect collect y))) 
(send bitmap-stream :bitbl t-to-sheet boole-xor 100 100 
stream (+ ex 150) (+ cy 150)))))) 

tvrwith-output-to-bitmap is similar to tvrwith-output-to-bitmap-stream with the 
additional feature that it copies the off-screen bitmap into a Lisp array and re- 
turns it. Use this when you wish to capture the result of some output operations 
in an array of bits, rather than (or in addition to) displaying the result on the 
screen. 

If you need an off-screen bitmap stream with a more permanent lifetime, you can 
use explicit allocation and deallocation. See the function 
tvrallocate-bitmap-stream. See the function tvrdeallocate-bitmap-stream. For ex- 
ample. 
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(defun off-screen-l ines-3 (&aux (stream *terminal-io*)) 
(fresh-line stream) 
(multiple-value-bind (ex cy) 

(send stream : visible-cursorpos-l imits) 
(let ((bitmap-stream (tv:al locate-bitmap-stream 

:for-stream stream 
host-allowed t 
width 100 :height 101))) 
(loop for X below 100 by 10 do 

(send bitmap-stream : clear-window) 
(loop for y downfrom (- 100 x) by 2 repeat 5 do 
(loop for X from x by 2 repeat 5 do 

(send bitmap-stream : draw-line x y))) 
(send bitmap-stream :bitbl t-to-sheet boole-xor 100 100 
stream (+ ex 150) (+ cy 150))) 
(tv : deal 1 ocate-bi tmap-stream bi tmap-stream) ) ) ) 

In a more realistic example, the calls to tvrallocate-bitmap-stream and 
tvrdeallocate-bitmap-stream would be in two different functions; otherwise 
tv:with-output-to-bitmap-stream would work just as well. 

The bitmap stream can become invalid if the window system is shut down and 
started again. It is best not to retain an off-screen bitmap stream permanently, but 
only for the duration of one operation. To minimize the overhead of allocating and 
deallocating a bitmap stream, you can allocate it when your application window is 
exposed and deallocate it when your application window is deexposed. 



Using Off-Screen Bitmaps with Low-level Drawing Primitives 

If you only need a bitmap, without the stream output and graphical operations of 
windows, either because you are using the low-level drawing primitives, or because 
you only do bitblt's, you can use the lower-level allocation primitives. Note that if 
you are using sys:%draw-xxx, you need to switch to tv:sheet-draw-xxx, since the 
system must be given a sheet in order to find the screen that connects to the host. 
There is no significant overhead in this switch. 

(defun off-screen-l ines-4 (&aux (sheet *terminal-io*)) 

(tv:with-temporary-sheet-bit-raster (bitmap sheet 100 100) 
(loop for X below 100 by 10 do 

(tv: sheet-force-access (sheet) ;Make sure has a screen array 

(letf (((tv: sheet-screen-array sheet) bitmap)) ;Use this one temporarily 
(tv: sheet-draw-rectangle 100 100 boole-andcl sheet) 
(loop for y downfrom (- 100 x) by 2 repeat 5 do 
(loop for X from x by 2 repeat 5 do 

(tv:sheet-draw-l ine x y boole-ior nil sheet)))) 
(tv:sheet-bitblt boole-xor 100 100 bitmap nil 200 200 sheet))))) 

If you need an off-screen bitmap with a more permanent lifetime, you can use ex- 
plicit allocation and deallocation. Instead of using tv:with-temporary-sheet-bit- 
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raster, you can call tv:%screen-allocate-sheet-temporary-bit-array and 
tv:%screen-deallocate-sheet-temporary-bit-array. Note that all these programs 
work on the XL and the 3600 series as well. 

For further information: 

See the macro tv:with-off-screen-drawing. 

See the function tv:%screen-allocate-sheet-temporary-bit-array. 
See the function tv:%screen-deallocate-sheet-temporary-bit-array. 
See the macro tv:with-temporary-sheet-bit-raster. 



tvrallocate-bitmap-streain &key :for-stream :host-allowed :width .-height :bits-per- 
pixel : graphics-transform Function 

Allocates an off-screen bitmap stream. You can perform textual and graphic output 
operations on the stream returned. The results will not be visible, since the 
bitmap is off-screen. You can use the :bitblt-to-sheet message to make the result 
visible by copying from the off-screen bitmap to a window. 

The bitmap stream can become invalid if the window system is shut down and 
started again. It is best not to retain an off-screen bitmap stream permanently, but 
only for the duration of one operation. To minimize the overhead of allocating and 
deallocating a bitmap stream, you can allocate it when your application window is 
exposed and deallocate it when your application window is deexposed. 

:for-stream A stream that outputs to a related window. This provides de- 

faults for the width, height, depth, and coordinate transforma- 
tion; if :host-allowed t is specified, the host owning the win- 
dow's screen will be used. 

:host-allowed True if the off-screen bitmap should be stored in host memory 

if possible. The default is false, which always uses Ivory mem- 
ory. :host-allowed t only works if :for-stream is specified. 

rwidth The initial width of the bitmap. It expands if necessary. 

rheight The initial height of the bitmap. It expands if necessary. 

:bits-per-pixel The depth of the bitmap. 

rgraphics-transform 

A coordinate transformation. The default is the stream's trans- 
form if :for-stream is specified. Otherwise, the identity trans- 
form is the default. 

See the message :bitblt-to-sheet. 

See the function tv:with-output-to-bitmap-stream. 

tvrdeallocate-bitmap-stream bitmap Function 
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Deallocates an off-screen bitmap stream when you are no longer using it. See the 
function tvrallocate-bitmap-stream. 



tv:bitmap-stream-copy-bitmap stream Function 

Makes a copy of the bitmap or raster associated with a stream and returns five 
values: 

• The bitmap 

• Left top 

• Right top 

• Left bottom 

• Right bottom 



:bitblt-to-sheet alu width height x y sheet sheet-x sheet-y Message 

Sends this message to an off-screen bitmap to copy its contents onto a window 
where it will be visible. This performs a bitblt from the width by height rectangle 
of the bitmap whose top-left corner is at (x,y) to the width by height rectangle of 
the window sheet whose top-left corner is at (sheet-x,sheet-y). 

See the function bitblt. 

See the function tvrallocate-bitmap-stream. 

See the function tv:with-output-to-bitmap-stream. 



mtb:*automatically-generate-pixmap-correspondences* Variable 

If true (the default), off-screen bitmaps that save the images of deexposed windows 
are placed in host memory if there is enough host memory. See the variable 
mtb : *pixmap-correspondence-memory- threshold* . 

If false, off-screen bitmaps that save the images of deexposed windows are always 
placed in Ivory memory. 

You must set this variable before the window system starts up. Typically, you 
would set it before saving a world. 



mtb:*pixmap-correspondence-memory-threshold* Variable 

Determines how much host memory is considered enough to enable off-screen 
bitmaps that save the images of deexposed windows to be placed in host memory. 
The amount of available host memory at the time the window system starts up 
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must be at least mtb:*pixmap-correspondence-memory-threshold* times the size 
of the screen. 



tvrwith-output-to-bitmap f&optional stream &key :for-stream : graphics-transform) 
&body body Function 

stream The stream to which to return the bitmap. 

:for-stream 

The stream for which the bitmap is intended. 

rgraphics-transform 

An optional transform to be applied. 

Returns a raster array and positions containing the image output by body. 

(defun bitmap-example (&optional (stream *standard-output*)) 
(graphics: with- room-for-graphics () 

(graphicsidraw-triangle 200 50 50 

:tile (tv:with-output-to-bitmap (bstream 
:for-stream stream) 
(graphics:draw-ci rcle 10 

: gray-level .25 : stream bstream) 
(graphicsidraw-regular-polygon 8 16 6 
: gray-level .75 
: stream bstream))))) 



tvrwith-output-to-bitmap-stream {bitmap-stream &rest args &key (for-stream nil) 
&allow-other-keys) &body body Function 

bitmap-stream 

A stream that is a raster array intended to hold the image generat- 
ed by body. 

args rfor-stream, the stream for which the bitmap is intended, and, op- 

tionally, rgraphics-transform, an optional transform to be applied. 

Binds bitmap-stream to a specially allocated stream that accepts the graphic output 
during execution of body. At any time, the :bitmap-and-edges message to this 
stream returns the current image. 



Batching Graphics Requests for Maclvory 

If you are drawing a number of graphics to a Maclvory screen (or remote off- 
screen bitmap), you may benefit from batching them together into single larger re- 
quests to the Macintosh. This does not cut down the actual drawing time, but re- 
duces the fixed communication overhead. This batching is only supported for lines 
and rectangles. 
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There are two new messages defined on windows (including those not attached to 
a Maclvory), : draw-multiple-lines and :draw-multiple-rectangles. Note that 
rdraw-multiple-lines is different from :draw-lines, in that each line is specified by 
points, rather than joining to the previous line segment. 

If you are using the higher level graphics:draw-line and 
graphicsrdraw-rectangle, you can still benefit from this batching by telling the 
system to buffer successive draw-line or draw-rectangle requests together. You will 
sacrifice a little bit of latency for better overall performance. To do this, (setf 
(rpc::rpc-screen-buffered-graphics-enabled <screen>) t). 



Direct Calls: a Linking Feature for Ivory-based Machines 

The Ivory architecture provides Direct Calls, a fast mechanism for function calls 
that is mostly usable for benchmarking and application delivery. 

In a normal Lisp call (an "indirect" call), the caller function has a pointer to the 
function cell containing the function to be called. When the call instruction is exe- 
cuted, it fetches the callee function from the function cell, and starts execution at 
the entry instruction of that function. The entry instruction sequence checks that 
the proper number of arguments was passed, initializes optional and keyword ar- 
guments, and then proceeds to execute the body of the called function. 

The normal call is called "indirect" because it fetches the contents of a function 
cell (indirects through it) rather than addressing the callee function directly. Lisp 
implementations typically implement calls as indirect calls in order to efficiently 
support redefinition at runtime: When a function is redefined, all the Lisp system 
has to do is change the contents of the function cell, and all callers will immedi- 
ately address the new definition. 

In a direct call, the caller addresses the callee function directly, without going 
through a function cell. For Lisp systems that implement function calls using the 
direct method, redefinition must change every caller of a function to address the 
new definition. This is typically very slow. 

Another optimization is possible when calls are implemented directly. Since rela- 
tively simple static analysis can determine how many arguments are being passed 
to a function, a direct call can often skip the preamble instructions that check for 
the proper number of arguments and initialize optional arguments. 

Genera 8.0 provides a linker for Ivory-based machines that performs both of the 
above optimizations. Depending on the application, its use can result in substantial 
performance improvements. The linker is not fully integrated with Genera. If there 
are direct calls to a function, and there is an attempt to redefine it, an error is 
signaled. Proceed options allow you to unlink definitions to a function before re- 
defining, or to proceed without unlinking. 

To globally link all functions, use (cl i : :1 ink-to-functions t). To globally unlink 
them, use (cl i : :unl ink-to-functions t). If you need finer control of which exist- 
ing functions should be linked or unlinked, refer to cli::link-to-functions and 
cli::unlink-to-functions for further information. 
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Regardless of whether any functions are hnked or not, newly compiled or loaded 
functions are always unlinked. 

Note: Because of architectural limitations, linking does not work on 3600-family 
machines. In order to get the additional performance benefit of linking, you must 
use an Ivory-based processor. 



cli::link-to-functions functions &optional link-noter verbose Function 

Links all calls to the functions specified by functions, functions is either a list of 
functions and/or function specs, or the symbol t, meaning all functions. This pro- 
cess takes up to twenty minutes, depending on your system configuration and the 
amount of software loaded. 



cli::unlink-to-functions functions &optional unlink-noter verbose Function 

Unlinks all calls to the functions specified by functions, functions is either a list of 
functions and/or function specs, or the symbol t, meaning all functions. This pro- 
cess takes about five minutes, depending on your system configuration and the 
amount of software loaded. 



Converting User Interfaces for Maclvory 

As a matter of principle, we recommend that you convert your programs in stages. 
If you wish, you can also convert your code by making all the source changes at 
once and then getting your program to run. However, this is generally a less effi- 
cient and more tedious process. 

You should be generally familiar with the user-level operation of the Maclvory and 
the high-level user-oriented description of how the Maclvory user interface works. 

• First, make sure that your program runs under Genera 7.2 on the 3600-series. 
Genera 7.2 is almost completely compatible with earlier releases. If you discover 
a large number of incompatibilities in converting to Genera 7.2, you are proba- 
bly using many undocumented internal interfaces. If nothing else, this should 
alert you to parts of your program that may run into problems on the Maclvory. 

• Make the changes necessary to get your program to run on the Ivory architec- 
ture. The Ivory is almost entirely source level compatible, so this should not be 
a major undertaking. 

• Genera 8.0 Ivory includes a number of changes to the scheduler and window 
system locking originally made in Genera 7.9 Ivory of which you should be 
aware. For further information, see the section "Converting to the New Sched- 
uler". Get your program to run on the Maclvory with minimal changes. There is 
only one major thing that is completely different on the Maclvory. There is no 
virtual memory array on the Lisp side that maps to the screen array of an ex- 
posed window. All drawing is done on the Macintosh side. If you are using 
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tv:sheet-screen-array or the tv:screen-array instance variable of a sheet, you 
need to change to go through the screen. This conversion is straightforward. In- 
stead of the very low level sys:%draw-xxx functions, you should use the 
tv:sheet-draw-xxx functions. For instance, these forms: 

(bitblt tv:alu-seta 100 100 raster (tv: sheet-screen-array sheet) 100 100) 
(bitblt tv:alu-seta 100 100 (tv: sheet-screen-array sheet) raster 100 100) 

become 

(tv:sheet-bitblt tv:alu-seta 100 100 raster nil 100 100 sheet) 
(tv:sheet-bitblt tv:alu-seta 100 100 nil raster 100 100 sheet) 

and this form: 

(tv:%draw-char-internal tto101 fonts :43vxms 10 10 tv:alu-xor tv: screen-array) 

becomes 

(tv: sheet-draw-glyph tto101 fonts :43vxms 10 10 tv:alu-xor) 

• The other incompatibility you may experience from the very start is the change 
in the screen size. If you think this will be a major problem, one good way to 
get started is to use a larger Macintosh monitor for the initial conversion. 
There are a variety available that approximate the size and pixel density of the 
3600-series screens. 

Maclvory differs from previous systems in that screen drawing is not done by the 
same processor that executes Lisp programs. Ivory executes Lisp, but the Macin- 
tosh does the screen drawing. When you execute a graphics or text output function 
or message, on 3600-series systems it does not return until the screen drawing is 
complete, but on Maclvory it queues a request for the Macintosh to do the screen 
drawing and returns immediately. If you have a program that needs to synchronize 
itself with the screen drawing, use the finish-output function (also available as 
the rfinish message). 

On 3600-series machines, finish-output on a window takes no appreciable time, 
but on Maclvory it waits until previously queued screen output has been complet- 
ed. An example of when you would need to do this is a program that draws contin- 
uously while a mouse or keyboard button is held down, and is supposed to stop as 
soon as the button is released. Without finish-output, the Ivory may stop as soon 
as the button is released, but the already-queued output will continue to be drawn 
for a noticeable amount of time. 

Bitblt operations where the source and destination are the same bitmap in host 
memory (which could be a window's image or an off-screen bitmap), and the 
source and destination subrectangles overlap, are not compatible with the 3600 and 
XL400 native window system. The embedded window system always chooses the di- 
rection of transfer so as to shift the contents of the bitmap. The native window 
system requires the caller to use the sign of the width and height arguments to 
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specify the direction of transfer, either shifting the contents of the bitmap or 
smearing it. In effect, you cannot use :bitblt-within-sheet for smearing effects on 
the embedded window system. 

Once your program has been ported to Maclvory, you should decide how to best 
make use of the system. 

• If your output uses the graphics:draw-xxx drawing functions it will use the 
QuickDraw drawing primitives directly. This can give a performance improve- 
ment of as much as 100 times. There are some incompatibilities, of course: 

° Stipples will always be 8x8. If yours do not have that phase, they may not 
align properly. 

° Unfilled shapes are stroked down and to the right of the mathematical shape 
with a rectangular pen, rather than half on either side. 

To make output exactly compatible, use the graphics:with-scan-conversion- 
mode special form. (See the special form graphics:with-scan-conversion-mode 
for further information.) 

• Keep in mind that coordinate system transformation is still performed on the 
Lisp side and that some shapes, such as tilted ellipses and dashed lines, are not 
supported by QuickDraw and therefore are still handled the slower, compatible 
way. As a general rule, however, if your graphics output already works compati- 
bly to the LGP2/LGP3, you will probably do fine using QuickDraw also. 

• If your output is using :draw-line or : draw- triangle and requires the ability to 
draw endpoints or abut objects seamlessly. Then you must use tv: screen-genera- 
graphics-compatibility of the screen to which you are drawing to locally enable 
compatibility for these operations. 

• If you are drawing to bit arrays and then copying them onto the screen to keep 
down the flicker time, you may wish to allocate these arrays on the Macintosh 
side and have the drawing done remotely. Then, the copying can also be done 
entirely on the Macintosh. 

If you are not concerned with compatibility among platforms, you may wish to con- 
vert your program to have a Macintosh- style user interface. A version of 
dwrdefine-program-framework is provided which provides high-level access to the 
major capabilities. For further information, see the special form dwrdefine-remote- 
program-framework. If you have special peripherals as part of your interface, 
such as a tablet, or wish to have special output, such as sound, you may need to 
make use of the Maclvory RPC facilities which access the Macintosh toolkit. These 
are relatively easy to use, given a basic knowledge of the Macintosh. Lisp-level 
support is given to remove most of the tedious host programming that would be 
necessary to communicate between the processors. 
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You may also wish to add some specific high-level request communications to tailor 
the performance of your application to the co-processor environment. Many well- 
defined operations can be moved onto the host. For instance, if you require very 
responsive rubber-band line style mouse tracking, you can define a procedure in 
the Macintosh mouse handler to do this and pass the results back the Ivory. You 
may wish to consult your Symbolics contact for help in meeting your specific 
needs. 



Example of Converting an Application for Maclvory 

This section describes how an existing application program — Document Examiner 
— was converted to work in Genera Ivory on the Maclvory platform. The goal was 
to present essentially the same Document Examiner on both the Maclvory and 
Symbolics 3600-series computers. 

In presenting this example we hope to illustrate some common problems in prepar- 
ing the user interface for Symbolics applications on Maclvory and their solutions. 
Some general steps are: 

• Recompiling the system for Genera Ivory. 

• Identifying any problems in existing interface design. 

• Redesigning the user interface, if necessary. Depending on the purpose of your 
application, you may need to rework elements to fit a smaller screen size, or to 
resemble a Macintosh style interface (described in the Macintosh User Interface 
Guidelines). 

• Implementing parallel user interfaces. 

• Refining the new implementation. 

Recompiling 

The first step is to recompile the system in a Genera Ivory world running on a 
Maclvory. (You can use the Compile System command or the compile-system 
form.) The recompilation occurred without any problems, producing a set of IBIN 
files. This application was not affected by any of the Genera Ivory changes. 

Finding Probiems with the Scaied-down Interface 

At this point. Document Examiner works on the Maclvory. When we try it on both 
a large display and a small display the scaling of the user interface from the usual 
Symbolics display to the large display on the Macintosh is acceptable. However, 
there are several problems with the scaled-down user interface on the small dis- 
play. 

The first problem occurs when SELECT D on a small screen results in an error. 
The cause of this error is that the size of the Viewer pane has been specified with 
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a fixed number of pixels, which exceeds the width of the small screen. When we 
change the constraints from a fixed number of pixels to proportional constraints, 
the immediate problem is solved. 

Document Examiner makes full use of a large screen. Each pane is important and 
necessary. When scaled, the two biggest problems are: 

• The formatted text in the Viewer pane depends on larger margins. 

• The appearance of the screen is excessively crowded. 

The Viewer shows the online documentation. The text was formatted expressly for 
a large screen, and when it is scaled down for the small screen, the text disap- 
pears beyond the right edge of the pane. This means that to read any given line, 
you would have to scroll the window toward the right, and then scroll back to the 
left to read the beginning of the next line. 

One solution might be to change the formatter code to format differently, accord- 
ing to the size of the display. Another possible solution is to redesign the user in- 
terface of Document Examiner for the small screen. Since it was a goal to have 
Document Examiner work for both the large and small screens, either solution 
would require two parallel versions of some code, each version targeted for a par- 
ticular size of display. (Either the formatter would work differently, based on the 
display, or the user interface would work differently.) 

We decided that redesigning the screen was preferable to changing the formatter. 
Using this approach we could solve both problems. Since the primary purpose of 
Document Examiner is to present documentation in a readable way, we wanted to 
grant more of the screen to the text being displayed. Along the way, we would 
have to reduce the amount of screen granted to other panes. 

To pursue this solution, we do the following: 

• Design a user interface targeted for the small screen 

• Find a way to choose the user interface at run-time, based on the size of the 
screen 

Designing thie User Interface for thie Small Screen 

Figure ! shows how Document Examiner appears on the large screen. 
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Document Examiner 



Example of Converting an Application for Maclvory 

This section describes how an existing application program — Docu- 
ment Examiner — was converted to work in Genera 7.3 Ivory on the 
Macivory platform. The goai was to present essentially tine same Doc- 
ument Examiner on botin tine Macivory and Symbolics computers. 

Reconnpiling 

Tine first step was to recompile the system in a Genera 7.3 Ivory 
world running on a Macivory. The recompilation occurred without any 
problems. This application was not affected by any of the Genera 7.3 

Ivory changes. 

Finding Problems with the Scaled-down Interface 

At this point, Document Examiner worked on the Macivory. We tried it 
on both a large display and a small display. The scaling of the user 
interface from the usual Symbolics display to the large display on the 
Macintosh was acceptable. However, we noticed several problems 
with the scaled-down user interface on the small display. 
Document Examiner makes full use of a large screen. Each pane is 
important and necessary. When scaled, the two biggest problems 
were: 

• The formatted text In the Default Viewer depended on larger mar- 
gins, and an error was signaled when trying to display a section of 
documentation 

• The appearance of the screen was excessively crowded 

The Default Viewer shows the online documentation. The text was for- 
matted expressly for a large screen, and the result of scaling It down 
for the small screen was an error. 

One possible solution was to change the formatter code to format 
Viewer: Default Viewer 
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Figure 95. Large-screen Appearance of Document Examiner 



We decided to use the entire width of the small screen for the Default Viewer. We 
placed the Current Candidates and Bookmarks panes below the Default Viewer, 
and the Command interaction pane below them. We reduced the size of these three 
panes in order to compensate for increasing the size of the Default Viewer pane. 

The Command Menu pane was the only remaining pane. Instead of dedicating 
space on the screen for it, we decided to make Document Examiner commands 
available via Macintosh- style pull-down menus. We created two new pull-down 
menus, called DocEx and Show, and we placed Document Examiner commands in 
these menus. 

Figure ! shows how Document Examiner appears on the small screen. Note that 
the two figures have the same scale factor, so you can get an idea of the differ- 
ence in the sizes of the two screens. 
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Example of Converting an AppMcAtion for MAclvory 

This section describes how an existing application program — Document Examiner - 
was converted to work in Genera 7.3 Ivory on the Maclvory platform. The goal wa 
to present essentially the same Document Examiner on both the Maclvory and Sym 



The first step was to recompile the system in a Genera 7.3 Ivory world running on a 
Maclvory. The recompilation occurred without any problems. This application was not 
affected by any of the Genera 7,3 Ivory changes, 

Finding Problems with the Scaled-down Interface 

At this point, Document Examiner worked on the Maclvory, We tried it on both a large 
display and a small display. The scaling of the user interface from the usual Symbolics 
tr: Default Viewer 
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Figure 96. Small-screen Appearance of Document Examiner 



The result is two different displays and modes of interaction, one for the large 
screen (which was unchanged from its existing state), and one for the small 
screen. Even though the mechanics of giving Document Examiner commands are 
slightly different, the general look-and-feel of the two interfaces are so similar that 
we believe users could easily switch between them. 



Implementing the Parallel User Interfaces 

We needed to provide two dwrdefine-program-framework forms, one for each 
screen. The form for the large screen already existed. 

In both forms, it was important to make the rselectable option be nil, the rsystem- 
menu option nil, and not to provide the :select-key option. As shown later, we will 
use a different mechanism for choosing the appropriate user interface at run-time. 

The primary difference in the two forms is in the rconfiguration option, highlight- 
ed here: 



Page 1006 



(dw : def i ne-program-f ramework doc-ex 

:pretty-name "Standard Document Examiner" 

: system-menu nil 

: selectable nil 

other-options... 

:conf igurations 

' ((dw: :main 

(: layout (dw: :main : column top-part bottom-part) 
(top-part : row title&vi ewer-pane candidates&bookmarks) 
(bottom-part : row command-pane menu-pane) 
(title&viewer-pane :column title-pane viewer-pane) 
(candidates&bookmarks : column candidate-pane bookmark-pane)) 
( :sizes 

(dw: :main (bottom-part 4 : lines command-pane) 

:then (top-part :even)) 
(bottom-part (command-pane 660.) 

:then (menu-pane :even)) 
(top-part (title&viewer-pane 660.) 

:then (candidates&bookmarks :even)) 
(title&viewer-pane (title-pane 1 :lines) 

:then (viewer-pane :even)) 
(candidates&bookmarks (candidate-pane 0.5) 

:then (bookmark-pane :even)))) 
)) 

(dw : def i ne-program-f ramework small-doc-ex 
:pretty-name "Small Document Examiner" 
: system-menu nil 
: selectable nil 
other-options... 
:conf igurations 
' ((dw: :main 

(: layout (dw: :main : column title&menu viewer-pane 

candidates&bookmarks command-pane) 
(title&menu : row title-pane tf+Ignore menu-pane) 
(candidates&bookmarks : row candidate-pane bookmark-pane)) 
( :sizes 

(dw: :main (command-pane 2 :lines) (title&menu 1 :lines title-pane) 
(candidates&bookmarks 4 : lines candidate-pane) 
:then (viewer-pane :even)) 
(title&menu (title-pane :even)) 
(candidates&bookmarks (candidate-pane 0.5) 

:then (bookmark-pane :even))) 
))) 
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Causing the Correct User Interface to be Selected at Run-time 

In the example below, we define the function choose-doc-ex-for-screen to perform 
a run-time query to determine the size of the screen. The result of this query se- 
lects the appropriate Document Examiner. 

The choose-doc-ex-for-screen function is "hooked into" the activity selection mech- 
anism by using tv:add-dispatching-select-key, a function documented for general 
use. The two function calls that follow do some additional cleanup work. These 
functions are not documented other than in this example. 

However, for now, if you need to choose the application based on run-time condi- 
tions, you can follow this example. 

(defun choose-doc-ex-for-screen (screen) 
(let ((screen-type 

(if (> (send (or screen tv: main-screen) : inside-width) 
950.) 
:big-screen 
:smal 1 -screen))) 
(ecase screen-type 

(:big-screen 'doc-ex) 

( :smal 1 -screen 'small-doc-ex)))) 

(tv : add-di spatchi ng-sel ect-key 
tt\D 'choose-doc-ex "Document Examiner" 'choose-doc-ex-for-screen t) 

;;; The following is necessary to put the "Document Examiner" entry 
;;; in the system menu, as D-P-F would do. 

(tv:add-activity-to-system-menu-programs-column "Document Examiner") 
(tv : add-to-system-menu-create-menu 

"Document Examiner" 

'(program-frame : program choose-doc-ex) 

"A Document Examiner program frame.") 



Condltionaiizlng the Prompt 

This final piece of code fine-tunes the application. The problem it addresses is that 
the usual Document Examiner prompt was too large for the small screen. This is 
because the prompt uses a device font, and device fonts are always the same size. 
They do not use the normal character- style mechanism, and are not automatically 
scaled down for the smaller screen. This code remedies the problem and selects 
the Document Examiner prompt based on the program running in the window. 

(defun type-of-docex-frame (window) 

(dw: : program-name (send (send window :al ias-for-selected-windows) 
: program))) 
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(defun default-dex-prompt (stream keyword) 
(ignore keyword) 

(with-character-style ('(:fix : roman mormal) stream) 
(ecase (type-of-docex-f name stream) 
(smal 1 -doc-ex 

(send stream :tyo tfXspace) 
(send stream :tyo tfXarrow: right-open-arrow)) 
(doc-ex 

(send stream :tyo tfXspace) 

(send stream :tyo tfXarrow: right-triangle))))) 



Maclvory User Interface Examples 

Etest Example 

etest.lisp 

; -*- Mode: LISP; Syntax: Common-lisp; Package: USER; Base: 10 -*- 

;> EXAMPLES-MESSAGE 

;> 

;> 

;> Symbolics hereby grants permission to customers to incorporate 
;> the examples in this file in any work belonging to customers. 
;> 

(dw : def i ne-remote-program-f ramework etest 
: selectable (:mac) 

:menu-level-order ' (, macintosh-internals: :*standard-remote-vi ewer-file-menu* 
, maci ntosh-i nternal s : : *standard-edi t-menu* 
"ETest") 
: inherit-f rom (;; Enable Lisp event handling 
mtb: : 1 isp-handles-event-uims 
maci ntosh-i nternal s : : remote-vi ewer-commands) 
: command-table ( :kbd-accelerator-p t : inherit-f rom '("remote-viewer-commands" 

;; Handle some events 
"Mac Window Control Commands")) 
: state-vari abl es ( (spl ash-wi ndow) ) 
) 
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; ; This scrawls a big black circle, showing that scroll bar tracking 
;; with Lisp callbacks works, 
(def i ne-etest-command (com-test-l 

: menu-accelerator "Test-1" 

:menu-level (:top-level (:mac "ETest")) 

: keyboard-accelerator tfXs-S) 


(let ((w (dw: : remote-program-open-viewer self :picture-p nil 

:left 40 :top 40 :width 600 :height 600 
:title "This is a test" 

: di spl ayer ' di spl ay-etest-startup-wi ndow) ) ) 
(send w :expose) ;only this creates the Macintosh side 

(multiple-value-bind (scrol 1-bar-h scrol 1-bar-v) 

(macintosh-internals: :mac-rpc-window-scrol 1-bars w) 
(mtb:_setctlmax scroll-bar-h 600) 
(mtb:_setctlmax scroll-bar-v 600)) 

(mtb: : force-update-window w) ; this shouldn't be needed 

)) 

(defun display-etest-startup-window (w mac-window) 
(ignore mac-window) 
(graphics:draw-ci rcle 200 200 100 istream w)) 

(def i ne-etest-command (com-splash : menu-accelerator "Splash" 

:menu-level (:top-level (:mac "ETest")) 
: keyboard-accelerator tfXs-F) 


(let ((w (if (member splash-window 

(macintosh-internals: :mac-rpc-program-windows self)) 
splash-window 
(setq splash-window 

(dw: : remote-program-open-viewer self :picture-p nil 
:left 5 :top 30 :width 470 iheight 370 
;; This title isn't really called 
;; for by the graphic design... 
:title "BearCal Splash" 
: di spl ayer (etest-spl ash-di spl ayer) ) ) ) ) ) 
(send w :expose) ;only this creates the Macintosh side 

(mtb: : force-update-window w) ; this shouldn't be needed 

)) 
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(defun etest-splash-displayer () 

(let* ((inner-pict-handle ()) 
(inner-pict-rect ()) 
(displayer 

(sys: named-lambda splash-displayer (ignore ignore) 
(when (null inner-pict-handle) 

;; The closure state needs some initialization 
(setq inner-pict-rect 

(mtb:make-rect :left 5 :top 30 :right 475 :bottom 400)) 
;; Pre-scribble into a pict so we won't need file I/O at redisplay time, 
(setq inner-pict-handle (mtb:_openpicture inner-pict-rect)) 
(with-open-f ile (in "sys: embedding; mac ivory; tool kit; examples; Splash. pict" 
: element-type '(unsigned-byte 8)) 
;; Open code mtb: :with-pict-f rom-f ile because it's on the sys host 
;; instead of on the local Mac. 
(let ((len (- (send in :length) 512))) 

;; The first 512 bytes of a pict file are useless. The rest is the pict. 
(send in :set-pointer 512) 

(stack-let ((pic (make-array len : element-type '(unsigned-byte 8)))) 
;; Read it from sys host into Lisp 
(send in :string-in "reading pict data" pic) 
;; Ship it over to the Mac. 

(mtb:with-mac-temp (pict :handle T : initial-contents pic) 
(let ((pict-rect (mtb:octet-ref-remote-handle 

(mtb:picture-picf rame pict)))) 
(mtb:_offsetrect pict-rect -20 -20) 
(mtb:_drawpicture pict pict-rect)))))) 
(mtb:_textsize 18) 

(mtb:_textface (mtbicconstant bold)) 
(mtb:_moveto 100 20) 

;; The octal 245 here is the Macintosh center-bullet char 
(mtb:_drawstring "Welcome to BearCal Airlines") 
(mtb:_moveto 115 330) 

;; The 322 and 323 are Macintosh sex-differentiated quotes 
(mtb:_drawstring "You'll have reservations...") 
(mtb:_closepicture)) 
;; This is what really does the display 
(mtb:_drawpicture inner-pict-handle inner-pict-rect)))) 
displayer)) 



Page 1011 



(def van *splash-resource-file-pathnaine* ftp" host : dsk : rl b : credi t-card-pi cts . rsrc" ) 

;;; Since PICT dialog items are identified by PICT resource numbers, 

;;; they must live in a resource file. We distribute a little rsrc file with the 

;;; picts for this example, but it's unlikely your Macintosh can read them from the sys host. 

;;; So, to run this example, you should do: 

; ; ; (mtb : copy-mac- image "sys: embedding; mac ivory; tool kit; examples; credi t-card-pi cts. rsrc" 

; ; ; "host : dsk :3'0Mr-/bZder: credi t-card-pi cts . rsrc") 

;;; to move the picts to your Macintosh's file system, and edit the defvar above, 

;;; changing "rib" to reflect its new home. 

(def i ne-etest-command (coin-dialog 

:menu-accelerator "Dialog" 

:menu-level (:top-level (:mac "ETest")) 

: keyboard-accelerator tfXs-D) 


(mtb:with-resf iles ((ignore *spl ash-resource-file-pathname*)) 
(let ((values (mtb: do-modal -dialog self (etest-dialog-items)))) 

;; of course this is all bogus 

(let ((results (with-output-to-string (s) 

(loop for (k v) on values by tf'cddr do 
(when (and v (not (equal v ""))) 
(format s " ~a: ~a~%" k v)))))) 
(unless (zerop (length results)) 

;; This is just a way to pop up something in lieu of updating 
;; some Statice database 
(maci ntosh-i nternal s : : di spl ay-di al og-hel p 
self 

(format nil "Conf i rm:~%~a" results) 
(mtb: :coerce-to-rect '(30 50 30 50)) 
500 400)))))) 

(defun etest-dialog-items () 

(let ((m (mtb: : make-dialog-item-maker))) 
(mtb: : set-dialog-face m 

: bounds '(30 50 482 335) 
title "BearCal Reservation System" 
proc-id (mtb:cconstant rDocProc)) 

(mtb : : add-several -di al og-i tems 
m 
'((:button (380 10 440 30) "GK" 

:check T :cluster okay-cluster :query-id okay-button) 
(:button (380 40 440 60) "Cancel" :query-id cancel -button) 
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(mtb 
m 
'( 



:text (10 10 110 26) "Passenger:") 

:edit (115 10 360 26) :query-id passenger irequired T 
loversee-cluster okay-cluster) 

:text (10 35 110 51) "Destination:") 

:edit (115 35 360 51) :query-id destination :required T 
;; :format1 "A" :format2 "[" 

) 

:text (10 60 110 76) "Depart:") 

:edit (115 60 185 76) :query-id depart :required T) 

:text (205 60 285 76) "Return:") 

:edit (290 60 360 76) :query-id return) 

:line (12 85 440 85)))) 

: add-several -di al og-i terns 

:text (10 95 110 111) "Address:") 

:edit (115 95 440 111) :query-id address) 

:text (10 120 110 136) "City:") 

:edit (115 120 330 136) :query-id city) 

:text (345 120 400 136) "State:") 

:edit (405 120 440 136) :query-id state) 

:text (10 145 110 161) "Zip:") 

:edit (115 145 220 161) :query-id zip) 

:text (235 145 295 161) "Phone:") 

:edit (300 145 440 161) :query-id phone) 

:line (12 170 440 170)) 

:text (370 180 440 196) "Payment:") 

: cluster payment-cluster 

(:pict (375 200 434 234) 100 

:query-id supercard) 
(:pict (375 240 434 274) 101 

:query-id creditcard)) 

(:line (360 175 360 275)))) 
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(mtb : : add-several -di al og-i terns 
m 

'((:text (10 180 110 196) "Incidentals:") 
(icluster incidentals-cluster 
(:check (15 200 110 216) "Smoking" : report T 

:query-id incidental-smoking) 
(:check (15 220 110 236) "Dinner" 

:query-id incidentals-dinner) 
(:check (15 240 110 256) "Movie" 

:query-id incidentals-movie) 
(:check (15 260 110 276) "Rental Car" : report T 
: query- id i nci dental -rental -car) ) ) ) 

(mtb : : add-several -di al og-i tems 
m 

'((:text (130 180 230 196) "Class") 
(: cluster class-cluster 
(:radio (135 200 230 216) "First" 

:query-id first-class) 
(: radio (135 220 230 236) "Coach" 

:query-id coach-class) 
(: radio (135 240 230 256) "Nook" 
:query-id nook-class)))) 

(mtb : : add-several -di al og-i tems 
m 

'((:text (250 180 350 196) "Seating") 
(icluster seating-cluster 
(: radio (255 200 350 216) "Window" 

:query-id seating-window) 
(: radio (255 220 350 236) "Center" 

:query-id seating-center) 
(:radio (255 240 350 256) "Aisle" 

:query-id seating-aisle)))) 
m)) 



Note: credit-card-picts.rsrc and splash.pict are binary data files used by the ETest 
commands, splash.pict is taken from the sys host, so you can try it out without 
further work. To use the credit-card-picts.rsrc demo, you must copy it onto your 
Macintosh before running the Dialog demo, and then edit a defvar in etest to say 
where the file has been copied. 



Pic-show Example 
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pic-show.lisp 

;;; -*- Mode: LISP; Syntax: Common-lisp; Package: (PIC-SHOW (MTB MACINTOSH-INTERNALS RPC SCL)); Base: 



;> EXAMPLES-MESSAGE 
;> 

;> 

;> Symbolics hereby grants permission to customers to incorporate 
;> the examples in this file in any work belonging to customers. 
;> 



(dw : def i ne-remote-program-f ramework pic-show 
: selectable (:mac) 

:menu-level-order ' (, macintosh-internals: :*standard-remote-vi ewer-file-menu* 
, maci ntosh-i nternal s : : *standard-edi t-menu* 
"PicShow") 
: inherit-f rom (;; Enable Lisp handling of events 
mtb: : 1 isp-handles-event-uims 
maci ntosh-i nternal s : : remote-vi ewer-commands) 
: command-table ( :kbd-accelerator-p t : inherit-f rom '("remote-viewer-commands" 

;; Handle some events 
"Mac Window Control Commands")) 
: state-vari abl es ( (wi ndow-pi ctures) ) 
) 



;;; Register file types and ways to read pictures from them 



(defvar *picture-readers* ()) 

(defun file-types-readable-as-pictures () 

(mapcar tf'first *picture-readers*)) 

(defun note-picture-reader (file-type function) 

(pushnew (list file-type function) *picture-readers* 
:key tt'first :test tt'string=)) 

(defun find-picture-reader (file-type) 

(second (assoc file-type *picture-readers* :test tt'string=))) 
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(def macro define-picture-reader (function-name file-type arglist &body body) 
' (progn 

(defun , function-name , arglist 

(declare (sys: function-parent , function-name define-picture-reader)) 
,@body) 
(note-picture-reader ', file-type ', function-name))) 



;;; Temporarily bind clipping region 



(defmacro with-clip-rect ((rect) &body body) 

' (with-cl ip-rect-1 , rect (sys: named-lambda with-clip-rect () ,@body))) 

(defun with-clip-rect-1 (rect continuation) 
(declare (sys:downward-funarg continuation)) 
(multiple-value-bind (left top right bottom) 
(dw: box-edges (mtb: :coerce-to-box rect)) 
(with-temps ((old-clip _newrgn _disposergn) 
(new-clip _newrgn _disposergn)) 
(_getcl ip old-cl ip) 

(_setrectrgn new-clip left top right bottom) 
(mtb: :unwind-protect-try 
(progn 

(_setclip new-clip) 
(funcall continuation)) 
(_setclip old-clip))))) 



;;; Here's the main command 
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(def ine-pic-show-command (com-show-file : menu-accelerator "Open" 

:menu-level (:top-level (:mac :file)) 
: keyboard-accelerator tfXs-O) 


;; It would be nice to change the mouse cursor to a wristwatch while preparing to show, 
(multiple-value-bind (name pict) 

;; Those types we know how to read and show. When there are more than 
;; four types this will have to use a file type filter instead of type list. 
;; See Inside Macintosh p. 1-524. 
(let ((types (f ile-types-readable-as-pictures))) 
(multiple-value-bind (vrefnum name type) 

(ez-sfgetfile :x-and-y '(100 100) :types types) 
(when vrefnum ;NIL if Cancel 

(with-open-refnum (refnum (fs: parse-pathname name "host") 

ivrefnum vrefnum) 
(values name (funcall (find-picture-reader type) refnum)))))) 
(when name ;NIL if Cancel 

(multiple-value-bind (rpc-window mac-window) 
;; Get a place to display this picture 
(get-the-right-window self pict name) 
(display-picture-window rpc-window mac-window))))) 



;;; Getting the pictures displayed 



;; A collection of things replicated for each file/picture/window/etc 

(def flavor window-picture (rpc-window mac-window scroll -bars pict zoom pict-rect display-rect) 


: ini table-instance- variables 
: readabl e-i nstance-vari abl es) 
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(def method (get-the-right-window pic-show) (pict name) 

(let ((pict-rect (octet-ref-remote-handle (picture-picf name pict)))) 
(multiple-value-bind (pleft ptop pright pbottom) 
(values (rect-left pict-rect 0) 
(rect-top pict-rect 0) 
(rect-right pict-rect 0) 
(rect-bottom pict-rect 0)) 
(let ((width (- pright pleft)) 

(height (- pbottom ptop))) 
(multiple-value-bind (max-right max-bottom) 

;; this should be based on something like screenBits, but that isn't 

;; readily accessible here. So pick something wrong, at least for large screens, 
;;but which should at least leave the size box on the screen, 
(values 600 400) 
(let* ((dy 20) 
(dx 4) 

(number-of-windows (length window-pictures)) 
;; Offset the windows a little each time. 

;; This doesn't really work when some windows have been closed, 
(left (+ 15 (* dx number-of-windows))) 
(top (+ 40 (* dy number-of-windows))) 
(right (min max-right (+ left width))) 
(bottom (min max-bottom (+ top height)))) 
(let ((rpc-window 

;; This is what with-output-to-viewer does 
(dw: : remote-program-open-viewer 
self :picture-p nil 

:left left :top top : right right : bottom bottom 
:title name 

: di spl ayer ' di spl ay-pi cture-wi ndow) ) ) 
(send rpc-window :expose) ;force creation on Macintosh side 

(let ((mac-window (macintosh-internals: :mac-rpc-window-mac-window rpc-window))) 
(multiple-value-bind (scrol 1-bar-h scrol 1-bar-v) 

(macintosh-internals: :mac-rpc-window-scrol 1-bars rpc-window) 
;; The scroll bars need to know how big a range they're scrolling 
;; This scroll bar stuff certainly deserves to have been done automatically 
;; by dw: : remote-program-open-viewer 
(mtb:_setctlmax scroll-bar-h width) 
(mtb:_setctlmax scroll-bar-v height) 
;; Stash away our data structures. 

;; This little application has no code to 

;; realize when a window is closed, 
(push (make-instance 

'window-picture 

: rpc-wi ndow rpc-wi ndow 

: mac-window mac-window 

:scroll-bars (list scroll-bar-h scroll-bar-v) 
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:pict pict 

:zoom 1 

:pict-rect pict-rect 

:display-rect (make-rect :left :top 

: right width :bottom height)) 
window-pictures) 
(values rpc-window mac-window)))))))))) 



;; This is the redisplayer. 

(defun display-picture-window (rpc-window mac-window) 

(ignore mac-window) 

;; forward this request to the controlling remote program. 

(display-picture-window-1 (macintosh-internals: :mac-rpc-window-program rpc-window) 

rpc-window)) 

(defmethod (display-picture-window-1 pic-show) (rpc-window) 

(let ((window-picture (find rpc-window window-pictures :key tf'window-picture-rpc-window))) 
(when window-picture 

;; forward it to the application data structure. 
(display-picture-window-2 window-picture)))) 

(defmethod (display-picture-window-2 window-picture) () 

(with-qd-port (mac-window) 

;; Draw the pict. Conceivably this could be accelerated in some cases by 
;; knowing something of the port's cliprgn. 
(_drawpicture pict display-rect))) 



;;; Ways to read files. 



;; Pict files written by MacDraw and many others 
(def ine-picture-reader get-the-pict "PICT" (refnum) 

(with-pict-f rom-f ile (pict pict-rect : refnum refnum :temporary nil) 

(ignore pict-rect) 

pict)) 
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; ; MacPaint files are written by many paint programs. 
;; The first 512 bytes are skipped. Then there are 720 rows 
;; each 72 bytes wide (where each row needs UnpackBits) . 
;; Fixed size, fixed resolution. 

(def ine-picture-reader get-the-pntg "PNTG" (refnum) 
(let ((len (- (_geteof refnum) 512))) 

;; We need a place to keep the file data to UnpackBits from 
(mtb:with-mac-temp (pntg :handle t :size len) 
(_setfpos refnum (cconstant fsFromStart) 512) 
(let {{err (with-handle-locked (pntg) 

;; Read the file contents, but only on the Macintosh side. 
(_fsread-remote refnum (_ptrf romhandle pntg) len)))) 
(unless (zerop err) 

; ; fsread-remote doesn't itself signal errors. 
(signal-mac-OS-error err))) 
; ; and a place to keep the unpacked bits. 
(mtb:with-mac-temp (the-bits :handle T :size (* 720 72)) 
(with-handle-locked (the-bits) 
(with-handle-locked (pntg) 

(_unpackbitsbyrows (_ptrf romhandle pntg) 

(_ptrf romhandle the-bits) 
72 720)) 
(with-rect (r (* 72 8) 720) 
(stack-let ((bitmap (make-bitmap 

;; the-bits must be locked while this is used as Ptr 
:baseaddr (_ptrf romhandle the-bits) 
: rowbytes 72 
: bounds r))) 
(let* ((the-port (_getport)) 

(portrect (octet-ref-remote-ptr (grafport-portrect the-port))) 
(portbits (octet-ref-remote-ptr (grafport-portbits the-port)))) 
;; Turn the bitMap into a Pict by drawing it. 
(let ((pict (_openpicture r))) 



(with-cl ip-rect (r) 

(_copybits bitmap portbits portrect portrect 
(cconstant srcCopy) 0)) 
(_closepicture) 
pict))))))))) 



Page 1020 



IDMP is a very simple file format for grayscale images. 
2 bytes, bits-per-pixel 
2 bytes, width 
2 bytes, height 
rest of file, the data, 
(def ine-picture-reader get-the-idmp "IDMP" (refnum) 
(let (bits-per-pixel width height) 

(mtb:with-mac-temp (data :handle T :size 0) 

(stack-let ((front (make-array 6 : element-type '(unsigned-byte 8) 

:fill-pointer 0))) 
(_fsread refnum 6 front) 

(setq bits-per-pixel (byte-swapped-8-aref-16 front 0) 
width (byte-swapped-8-aref-16 front 2) 
height (byte-swapped-8-aref-16 front 4))) 
(let ((len (/ (* width height bits-per-pixel) 8))) 
(_sethandlesize data len) 
(let {{err (with-handle-locked (data) 

(_fsread-remote refnum (_ptrf romhandle data) len)))) 
(unless (zerop err) 

(signal-mac-OS-error err)))) 
; ; Compute the color map for n-bit grayscale 
(let* ((n-colors (ash 1 bits-per-pixel)) 
(shift (- 16 bits-per-pixel)) 
(rgb (make-rgbcolor)) 

(r (make-rect :left :top :right width :bottom height)) 
(the-port (_getport))) 
(with-temps ((palette (lambda () 

(_newpalette n-colors 

(cconstant pmTolerant) 0)) 
_di sposepal ette) ) 
(loop for i from below n-colors do 
(let ((k (lognot (ash i shift)))) 

(setf (rgbcolor-red rgb 0) (Idb (byte 16 0) k)) 
(setf (rgbcolor-green rgb 0) (round (* .9 (Idb (byte 16 0) k)))) 
(setf (rgbcolor-blue rgb 0) (round (* .9 (Idb (byte 16 0) k)))) 
(_setentrycolor palette i rgb))) 
(with-temps ((pmh _newpixmap _dispospixmap)) 
(with-handle-locked (data) 
(with-handle-locked (pmh) 

;; This could have used a bunch of (setf (octet-ref-remote-handle ...)), 

;; but since several fields are being altered, it seemed better to 

;; drag the whole thing over to Lisp, fiddle with it, and send it back. 

;; A pixMap is only 50 bytes anyway. 

(with-mac-struct (pixmap pixmap :handle pmh) 

(setf (pixmap-baseaddr pixmap 0) (_ptrf romhandle data)) 
(setf (pixmap-rowbytes pixmap 0) 
(logior ttx8000 
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; ; See Inside Macintosh p. \l-53. 
(/ (* width bits-per-pixel ) 8))) 
(setf (pixmap-bounds pixmap 0) r) 
(setf (pixmap-pixelsize pixmap 0) bits-per-pixel) 
(setf (pixmap-cmpsize pixmap 0) bits-per-pixel) 
(_wri te-opaque-bytes-i nto-handl e 
pmh (length pixmap) pixmap)) 
;; Now don't ask me why we bring it back again. Maybe it's because 
;; drawpixmap insists on having a Lisp pixMap to transport back to 
;; the Macintosh side, 
(with-mac-struct (pixmap pixmap :handle pmh) 

(_palette2ctab palette (pixmap-pmtable pixmap 0)) 

(let ((portrect (octet-ref-remote-ptr (grafport-portrect the-port))) 
(portbits (octet-ref-remote-ptr (grafport-portbits the-port)))) 
(let ((pict (_openpicture r))) 

(unless (typep portbits '(vector (unsigned-byte 8))) 

(error "Bad portbits")) 
(with-cl ip-rect (r) 

(_drawpixmap pixmap portrect portrect 
(cconstant srcCopy) 0)) 
(_closepicture) 
pict))))))))))) 



; ; ; An attempt at making this toy a little more interesting 



;; The menu item for this should be disabled when there are no pictures. 

(def ine-pic-show-command (com-set-zoom : menu-accelerator "Set Zoom" 

;; I think the -c- gets lost somehow, which 
;; puts this on the same key as [Edit / Undo], 
;; which fails to adhere to the Macintosh UI guidelines. 
: keyboard-accelerator tfXs-c-Z 
:menu-level (:top-level (:mac "PicShow"))) 
((zoom 'number :default 1 :prompt "Zoom")) 
(let ((wp (front-window-picture self))) 
(if wp 

(set-window-picture-zoom wp zoom) 
(beep)))) 

(def method (front-window-picture pic-show) () 

(let ((mac-window (_f rontwindow))) 

;; Look up the front Macintosh window in our application data structures, 
(let ((window-picture (find mac-window window-pictures :key tf'window-picture-mac-window))) 
window-picture))) 
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(defmethod (set-window-picture-zoom window-picture) (new-zoom) 
(let ((old-zoom zoom)) 
(setq zoom new-zoom) 
(with-qd-port (mac-window) 

;; By invalidating the old and new sizes, we hope to cause correct redisplay 
(_invalrect display-rect) 
; ; Compute new edges 

(let ((left (round (* zoom (rect-left pict-rect 0)))) 
(top (round (* zoom (rect-top pict-rect 0)))) 
(right (round (* zoom (rect-right pict-rect 0)))) 
(bottom (round (* zoom (rect-bottom pict-rect 0))))) 
;; Update scroll bars 
(flet ((foo (s v) 

(let ((old (_getctl value s))) 

;; Set the max before the value — if we did the value first, 
;; it might get clipped to the max. 
(_setctlmax s v) 

(_setctl value s (round old (/ zoom old-zoom)))))) 
(foo (first scroll-bars) (- right left)) 
(foo (second scroll -bars) (- bottom top))) 
;; Update the stored version 
(setf (rect-left display-rect 0) (round left)) 
(setf (rect-top display-rect 0) (round top)) 
(setf (rect-right display-rect 0) (round right)) 
(setf (rect-bottom display-rect 0) (round bottom)) 
(_invalrect display-rect))))) 



; ; ; Ideas for enhancements 



til 

There should be a Windows command which offers a menu of open picture windows, 

and when you pick one, selects the corresponding Macintosh window. 

There could be a Crop command which lets you pick a rectangle and reduce 
the image to only that size. 

There could be keyboard accelerators to zoom and unzoom (and scroll, too) without 
messing around with the dialog. 

The _openpicture/_closepicture stuff should be macroized into making-picture 

\ti 

(compile-flavor-methods pic-show window-picture) 
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Menubar Example 

menubar.lisp 

-*- Mode: LISP; Syntax: Common-lisp; Package: MAC-TOOLBOX; Base: 10 -*- 

> EXAMPLES-MESSAGE 
> 

> 

> Symbolics hereby grants permission to customers to incorporate 

> the examples in this file in any work belonging to customers. 
> 



You want to run show-menu-bar-menus . 

Also look at menu-item-feature and its setf method. 



Structure definitions from Inside Macintosh \l-229 



(def ine-octet-structure (MenuRec : access-type :byte-swapped-8) 
(menuOH menuhandle) 
(menuLeft integer-16)) 

(def ine-octet-structure (HMenuRec : access-type :byte-swapped-8) 
(menuHOH menuhandle) 
(* integer-16)) 

; ; field types too 

(def ine-octet-structure-fi eld-type MenuRec () (array index) 

: result-type T 

:size (octet-structure-total-size (MenuRec .x. 0)) 

:data ' (macintosh-internals: :make-included-octet-structure MenuRec , array , index)) 

(def ine-octet-structure-fi eld-type HMenuRec () (array index) 
: result-type T 

:size (octet-structure-total-size (HMenuRec .x. 0)) 
:data ' (macintosh-internals: :make-included-octet-structure HMenuRec , array , index)) 
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(def ine-octet-structure (DynamicMenuList : access-type :byte-swapped-8) 
(lastMenu cardinal-16) 
(lastRight cardinal-16) 
(mbResID cardinal-16) 
(menu (vector MenuRec (/ lastMenu 6))) 
(lastHMenu cardinal-16) 
(menuTitleSave pixmaphandle) 
(hMenu (vector HMenuRec (/ lastHMenu 6))) 
) 

;; This is the anonymous internal structure in IM \/-230 

(def ine-octet-structure (menu-item : access-type :byte-swapped-8) 

(itemStringLength cardinal-8) 

(itemString (vector character-8 itemStringLength)) 

(itemlcon cardinal-8) 

(itemCmd cardinal-8) ;it's not always character-8 

(itemMark cardinal-8) ;it's not always character-8 

(itemStyle Style) 

) 

(defmacro string-from-str255-reference (reference) 
(declare (values string next-index)) 
' (string-f rom-str255 

, (second reference) 

(octet-structure- field- index , reference))) 

(defun string-from-str255 (octet-array index &key area) 
(declare (values string next-index)) 
(let ((len (aref octet-array index))) 
(let ((result (if (eql area : stack) 

(sys: make-stack-array len : element-type 'string-char) 
(make-string len :area area))) 
(octet-array octet-array)) 
(declare (sysiarray-register result octet-array)) 
(dotimes (i len) 

(setf (aref result i) (code-char (aref octet-array (+ index i 1))))) 
(values result (+ index len 1))))) 

(defmacro string=-str255-reference (string reference) 

' (string=-str255-reference-1 , string , (second reference) 

(octet-structure- field- index , reference))) 



Page 1025 



(defun string=-str255-reference-l (string octet-array index) 
(let ((len (length string))) 

(and (= len (aref octet-array index)) 

(let ((string string) (octet-array octet-array)) 
(declare (sysiarray-register string octet-array)) 
(dotimes (i len T) 

(unless (char= (aref string i) (code-char (aref octet-array (+ index i 1)))) 
(return nil))))))) 



;;; The application code 



;; This is the thing to run 
(defun show-menu-bar-menus () 

(with-temps ((menu-bar-handle _getmenubar _disposhandle)) 
(with-mac-struct (menu-bar () :handle menu-bar-handle) 
(format T "~&There are ~d items, right edge ~d" 

(/ (dynamicmenul ist-lastmenu menu-bar 0) 6) 
(dynamicmenul ist-lastright menu-bar 0)) 
(let ((mbdf (dynamicmenul ist-mbResID menu-bar 0))) 
(when (^ mbdf 0) 

(format T "~&Drawn by MBDF resid ~d, variant ~d" 
(Idb (byte 13 3) mbdf) 
(Idb (byte 3 0) mbdf)))) 
(domap ((item (dynamicmenul ist-menu menu-bar 0))) 

(with-mac-struct (menuinfo () :handle (menurec-menuoh item 0)) 
(show-menuinfo menuinfo 

(menurec-menuleft item 0)))) 
(format T "~&There are ~d hierarchical/popup menu items" 

(/ (dynamicmenul ist-lastHmenu menu-bar 0) 6)) 
(domap ((item (dynamicmenul ist-hmenu menu-bar 0))) 

(with-mac-struct (hmenuinfo () :handle (hmenurec-menuhoh item 0)) 
(show-menuinfo hmenuinfo ())))))) 



Page 1026 



(defun show-menuinfo (menuinfo left) 
(format T "~& Menu ID ~d, size ~dw*~dh" 
(menuinfo-menuid menuinfo 0) 
(menuinfo-menuwidth menuinfo 0) 
(menuinfo-menuheight menuinfo 0) 

) 
(when left (format T ", left ~d" left)) 
(let ((def (menuinfo-menuProc menuinfo 0))) 
(when (^ def 0) 

(format T ", defProc handle 0x~x" def))) 
(let ((enables (Idb (byte 32 0) (menuinfo-enablePlags menuinfo 0)))) 
(multiple-value-bind (title next-index) 

(string-f rom-str255-reference (menuinfo-menudata menuinfo 0)) 
(format T "~& Title ~s" title) 

(unless (Idb-test (byte 1 0) enables) (format T " [menu disabled]")) 
(let ((index next-index)) 
(loop for i from 1 do 

(multiple-value-bind (item-text icon-number kbd-equivalent 

checkmark-char char-style next-index) 
(menu-item-stuff menuinfo index) 
(when (null item-text) (return)) 
(format T "~& Item ~s" item-text) 
(when (^ icon-number 0) 

(format T ", icon ~d" (+ 256 icon-number))) 
(unless (eql kbd-equivalent 0) 
(cond ((eql kbd-equivalent tfxIB) 

;; hierarchical menu, see IM \l-236 
(format T ", submenu ~d" checkmark-char)) 
(T 
(if (< tfxIB kbd-equivalent tfxIP) 

(format T ", kbd 0x~x" kbd-equivalent) 
(format T ", kbd ~c" kbd-equivalent)) 
(unless (eql checkmark-char 0) 

(format T ", checkmark ~c" checkmark-char))))) 
(when (^ char-style 0) 

;; decode bits of the enum Style 

(format T ", style ~d" char-style)) 
(unless (Idb-test (byte 1 i) enables) 

(format T " [disabled]")) 
(setq index next-index))) 
(unless (= index (length menuinfo)) 

(format T "~& Extra ~d bytes" (- (length menuinfo) index))))))) 
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(defun menu-item-stuff (octet-array index) 

(declare (values item-text icon-number kbd-equivalent checkmark-char char-style next-index)) 
(when (> (menu-item-itemStringLength octet-array index) 0) 
(values (menu-item-itemString octet-array index) 
(menu-item-itemlcon octet-array index) 
(menu-item-itemCmd octet-array index) 
(menu-item-itemMark octet-array index) 
(menu-item-itemStyle octet-array index) 
(octet-structure- total -size 

(menu-item octet-array index))))) 



;;; Here's a little more 



;;; Pass nil or the-item-text to refer the the menu itself 
(defun menu-item-feature (menu-text item-text feature) 

(check-type feature (member :text : enabled : checked :mark :icon : style :key)) 
(multiple-value-bind (handle item-number) 

(menu-handle-and-item-number menu-text item-text) 
(ecase feature 
( : text 

(with-str255 (string) 

(_GetItem handle item-number string) 
(copy-seq string))) 
( : enabled 

(if (< item-number 32) 

(with-mac-struct (menuinfo () :handle handle) 

(Idb-test (byte 1 item-number) (menuinfo-enableFlags menuinfo 0))) 

T)) 
( : checked 

(not (zerop (_getitemmark handle item-number)))) 
( :mark 

(let ((number (_getitemmark handle item-number))) 
(if (zerop number) nil (code-char number)))) 
( : icon 

(let ((n (_getitemicon handle item-number))) 
(if (zerop n) nil (+ n 256)))) 
(: style 

;; could decode the bits here 

(_getitemstyle handle item-number)) 
(:key 

(_getitemcmd handle item-number)) 
))) 
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; ; Internal, for use by setf below 

(defun set-menu-item-feature (menu-text item-text feature value) 

(check-type feature (member :text : enabled : checked :mark :icon : style :key)) 
(multiple-value-bind (handle item-number) 

(menu-handle-and-item-number menu-text item-text) 
(ecase feature 
( : text 

(_SetItem handle item-number value)) 
( : enabled 

(if (< item-number 32) 
(if value 

(_enableitem handle item-number) 
(_disableitem handle item-number)) 
(check-type value (not null)))) 
( : checked 

(_checkitem handle item-number value)) 
( :mark 

(_setitemmark handle item-number (if value (char-code value) 0))) 
( : icon 

(check-type value (or null (integer 256 (512)))) 
(_setitemicon handle item-number (if value (- value 256) 0))) 
(: style 

;; could encode the bits here 
(check-type value (integer (256))) 
(_setitemstyle handle item-number value)) 
(:key 

(_setitemcmd handle item-number (if value (char-code value) 0))) 
))) 

(defsetf menu-item-feature set-menu-item-feature) 
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; ; The thing that finds the handle and item number 

(defun menu-handle-and-item-number (the-menu-text the-item-text &key (if-not-found : error)) 
(block found 

(flet ((check-menuinfo (handle) 

(with-mac-struct (menuinfo () :handle handle) 

(when (string=-str255-reference the-menu-text (menuinfo-menudata menuinfo 0)) 
(when (null the-item-text) 

(return-from found (values handle 0))) 
(let ((next-index (let ((i (octet-structure-field-index 

(menuinfo-menudata menuinfo 0)))) 
(+ i 1 (aref menuinfo i))))) 
(let ((index next-index)) 

(loop for i from 1 do ;it -IS- 1-origin, right? 

(multiple-value-bind (item-text icon-number kbd-equivalent 

checkmark-char char-style next-index) 
(menu-item-stuff menuinfo index) 
(ignore icon-number kbd-equivalent checkmark-char char-style) 
(when (null item-text) (return)) 
(when (string= item-text the-item-text) 
(return-from found 
(values handle i))) 
(setq index next-index))))))))) 
(with-temps ((menu-bar-handle _getmenubar _disposhandle)) 
(with-mac-struct (menu-bar () :handle menu-bar-handle) 
(domap ((item (dynamicmenul ist-menu menu-bar 0))) 

(check-menuinfo (menurec-menuoh item 0))) 
(domap ((item (dynamicmenul ist-hmenu menu-bar 0))) 
(check-menuinfo (hmenurec-menuhoh item 0)))))) 
(ecase if-not-found 

(:error (error "Failed to find Macintosh menu ~s item ~s" the-menu-text the-item-text)) 
((nil) )) 
)) 

ttll 

;;Here are some trivial things you can do with the Genera menu bar 

;; A Keyboard accelerator to get at the Keyboard Kontrol 

(setf (menu-item-feature "Keyboard" "Keyboard Control" :key) tfXK) 

;; Call the finder with a single keystroke! (clover-F) 

(setf (menu-item-feature "V" "Finder" :key) tfXF) 

;; MacGS seems to use the keystroke internally — restore with this 

(setf (menu-item-feature "V" "Finder" :key) (code-char 29)) 

(setf (menu-item-feature "Options" "Keyboard" :style) 
(+ (cconstant bold) (cconstant shadow))) 
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Show-icons Example 

show-icons. lisp 

; -*- Mode: LISP; Syntax: Common-lisp; Package: MAC-TOOLBOX; Base: 10 -*- 

;> EXAMPLES-MESSAGE 

;> 

;> 

;> Symbolics hereby grants permission to customers to incorporate 
;> the examples in this file in any work belonging to customers. 
;> 

(defun show-all-mac-cursors () 

(do-rsrcs (curs ignore ignore) ("CURS" :all :load T) 

(draw-mac-cursor-at-cursorpos : handle curs)) 
(send *standard-output* : increment-cursorpos 16)) 

(defun show-all-mac-icons () 

(do-rsrcs (h id name) ("ICON" :all :load T) 
(format T "~%ICON ~d ~s~%" id name) 
(draw-mac-icon-at-cursorpos :handle h) 
(send *standard-output* : increment-cursorpos 32)) 
(do-rsrcs (h id name) ("ICNtf" :all :load T) 
(format T "~%ICNtt ~d ~s~%" id name) 
(with-mac-struct (icns () :handle h) 
(let ((icon-length (/ (* 32 32) 8))) 

(loop for i from below (length icns) by icon-length do 

(stack-let ((icon (make-array icon-length :element-type '(unsigned-byte 8) 

:displaced-to icns 
:displaced-index-offset i))) 
(draw-mac-icon-at-cursorpos :struct icon))))) 
(send *standard-output* : increment-cursorpos 32))) 
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(defun draw-mac-icon-at-cursorpos (&key resnum handle struct) 
(cond (struct 

(stack-let* ((struct struct) 

(image (make-array '(32 32) :element-type 'bit)) 
(images (make-array (/ (* 32 32) 8) 

: element-type '(unsigned-byte 8) 
:displaced-to image))) 
(declare (sysiarray-register struct image8)) 
(dotimes (j 128) 

(setf (aref image8 j) (sys:bit-reverse-8 (aref struct j)))) 
(multiple-value-bind (x y) (send *standard-output* : read-cursorpos) 
(graphics:draw-image image x y) 

(send *standard-output* : increment-cursorpos 36 0)))) 
(resnum 
(with-resource (icon "ICON" resnum) 

(draw-mac-icon-at-cursorpos istruct icon))) 
(handle 
(with-mac-struct (icon () :handle handle) 
(draw-mac-icon-at-cursorpos istruct icon))) 
(T ))) 

(defun draw-mac-cursor-at-cursorpos (&key resnum handle struct) 
(cond (struct 

(check-type struct (vector (unsigned-byte 8) 68)) 
(stack-let* ((image (make-array '(32 32) :element-type 'bit)) 

(image8 (make-array 64 :element-type '(unsigned-byte 8) 
:displaced-to image))) 
(let ((i 0) (j 0)) 
(dotimes (row 16) 
(dotimes (col 2) 

(setf (aref image8 j) (sys:bit-reverse-8 (aref struct i))) 
(incf i) 
(incf j)) 
(incf j 2))) 
(multiple-value-bind (x y) (send *standard-output* : read-cursorpos) 
(graphics:draw-image image x y) 

(send *standard-output* : increment-cursorpos 20 0)))) 
(resnum 
(with-resource (struct "CURS" resnum) 

(draw-mac-cursor-at-cursorpos : struct struct))) 
(handle 
(with-mac-struct (struct () :handle handle) 

(draw-mac-cursor-at-cursorpos : struct struct))) 
(T ))) 
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Maclvory Interface to HyperCard 

The Hyperlvory Demo 

What is Hyperlvory? 

Hyperlvory is a collection of demos that illustrates the close communication and 
integration possible between Ivory and a host HyperCard application. A similar ap- 
proach could be used with any host application that allows extension, not just Hy- 
perCard. This kind of integration and communication can also be built into new 
applications, as described in the "Maclvory Programmer's Reference". 

Hyperlvory offers examples of how to do the extension. The Hyperlvory stack illus- 
trates some of what Ivory could bring to HyperCard, including: 

• Simple Lisp, as used in the EVAL Service and Command Service 

• Programs, such as the Stack Dumper and Iconizer 

• Hypertext capabilities, shown in a static form in the Doc Ex demo, which pro- 
vides an interface to the same doc that Document Examiner gets you; and 
shown in a computed form in the Flavor Demo, which uses Genera Flavor com- 
ponents and dependents. 

• Statice, as used in the database for Mug Shots. 

• Joshua/ES, as used in Map Routes. 

The Lisp code for these demos is in the directory 

SYS:EMBEDDING;MAClVORY;HYPERCARD;. 

To use these demos: 

1. Load the system HyperCard/MacIvory into Genera before using the Hyper- 
lvory demos. 

2. Double-click on the Hyperlvory icon, located in the Maclvory Applications 
folder, to activate the stack. 

You do not need to run the Genera icon when you run the Hyperlvory stack. The 
Hyperlvory stack will boot your Ivory if it is not booted. Or, you can run Genera 
to boot and set up the software, then use [File / Quit] to get out of Genera and 
then start up HyperCard. Sometimes it's useful to run Genera and HyperCard at 
the same time (using MultiFinder), so you can use Genera to debug your XFCN 
servers. 

The demo stack consists of these cards: 

Hyperlvory Apologia 

This card explains the general purpose of Hyperlvory and 
presents some overall information about the cards. 



Page 1033 



Hyperlvory menu This card is a menu of the available demos. 

IvoryCom This card provides low-level interface directly to the Calllvory 

XFCN. 

Stack Dumper The Stack Dumper card dumps much of a HyperCard stack in- 

to a text file, using a Lisp-readable syntax. You should proba- 
bly read the code if you anticipate using this seriously. 

EVAL Service EVAL Service evaluates Lisp forms you type in. 

Ivory At Your Command 

You can issue and activate Genera Command Processor com- 
mands with from this card. 

The Obligatory Flavor Demo 

This card returns the dependents and components of a flavor 
you specify. This demo goes beyond ordinary hypertext in that 
it computes dynamically variable results rather than linking to 
prewritten text. 

Spellbound A spelling checker. See the section "Example of Creating a Cal- 

llvory Server". 

The Hypertext Delivery Story 

This card provides an interface to the Genera Document Ex- 
aminer. 

Iconizer Uses Lisp code to scan the Finder Desktop to extract icons and 

paste them onto cards. 

Map This demo computes and displays routes among various towns. 

Mug Shots This demo illustrates the integration of HyperCard with Stat- 

ice. It displays "mug shots" from a Statice database. 

What's in it? 

Hyperlvory consists of a HyperCard stack and some Lisp files. In the stack itself 
are: 

• An XFCN so HyperTalk scripts can talk to Ivory. 

• Some HyperTalk scripting so HyperTalk scripts can understand Ivory's reply. 

• Several cards with their own buttons, scripts, and so on. 
In Genera itself: 

• General code for fielding HyperCard requests and for calling back into Hyper- 
Card. 
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• Application-specific code to handle requests from the scripts of specific cards 
and their buttons. 

• HyperCard-specific "glue" code. 

How does it work? 

The XFCN is the heart. It provides a HyperTalk function Za^Myo^y {routineName, 
argsString) -> resul tString. This uses the RFC mechanism to pass the request to 
Ivory. The RFC server looks up the Lisp XFCN server corresponding to routine- 
Name, and calls it, passing it the argsString. The values returned by the server 
routine, whatever it types to *standard-output*, and any errors, are returned in 
resul tString. 

While the XFCN is awaiting the server's response, it provides RFC service to 
Ivory — including, notably, a path for calling back into HyperCard. This enables 
Lisp code to do virtually anything within HyperCard that a HyperTalk script could 
do. 

You may wish to consult the Macintosh HyperCard User's Guide or Macintosh Hy- 
perCard Script Language Guide: the HyperTalk Language for detailed documenta- 
tion on these topics. 

HyperTalk Routines 

The XFCN "Calllvory" is attached to the Hyperlvory stack as for any XFCN. The 
result extractors are in the script of the Hyperlvory stack. See the section "Adding 
a Calllvory Server" for an example of using these routines. 

Maclvory includes these new HyperTalk routines for calling Ivory and for extract- 
ing from the results returned by calling Ivory: 



Calllvory HyperTalk Routine 

HyperTalk Syntax: put Ca^M\Jory(routineName, routineArgs) into results 

Description: Calls Ivory's XFCN server named routineName, passing it the 

string routineArgs. Whatever that server routine returns is put 
into the HyperCard container results. 

results receives in a single string the description of the Lisp 
error that occurred, if any; everything the server typed to its 
*standard-output*; and each value returned by the server. Use 
the HyperTalk functions ResultError, ResultTypeout, Result- 
Values, ResultNValues, ResultValue to extract portions of the 
returned value. If a Lisp value returned is a string, that string 
is returned to HyperCard; otherwise its write-to-string is re- 
turned. 
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ResultError HyperTalk Routine 

HyperTalk Syntax: put Resu^tError (results) into xxx 

Description: Extracts the text of a Lisp error, if one occurred while the 

server ran. Otherwise, leaves this empty. 



ResultTypeout HyperTalk Routine 

HyperTalk Syntax: put ResultTypeout (reswZte) into xxx 

Description: Extracts server typeout to *standard-output*, if any. 

ResultValues HyperTalk Routine 

HyperTalk Syntax: put Resul t\/alues(resMZte) into xxx 

Description: Extracts all Lisp values returned by the server, separated by 

return characters. 

ResultNValues HyperTalk Routine 

HyperTalk Syntax: put Resul tN\/alues(resMZte) into xxx 

Description: Extracts the number of Lisp values returned by the server. 

ResultValue HyperTalk Routine 

HyperTalk Syntax: put Resul t\/alue(resMZ^, valueNumber) into xxx 

Description: Extracts a specific Lisp value returned by the server. The first 

value is valueNumber 1. 

Lisp Routines 

In addition to the Lisp functions and macros described here, you can also use all 
the Macintosh toolbox routines listed in "Lisp Functions That Access the Macin- 
tosh Toolbox". 

mtb:define-xfcn-server name arglist &body body Macro 
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Defines a XFCN server name callable by HyperCard. Its arglist should be of length 
one, receiving the string passed by the invoking call to the HyperTalk XFCN Cal- 
llvory. 

The server is run within a condition-bind for error; princ-to-string of the error is 
returned to HyperCard. In some circumstances it may be desirable to debug prob- 
lems using the Debugger. Set *debug-hc-server-flag* to T to disable the condition- 
bind. 

See the section "Hints for Writing Calllvory Servers" for related information". 
Functions Useful to Call from XFCN Servers 

mtb:hc-chunk-character string from &optional to Function 

Returns a substring of string from character from to to, or the one character at 
from. Similar to HyperTalk's character chunk expression, except mtb:hc-chunk- 
character is zero-based. This function is useful for destructuring the string argu- 
ment passed to XFCN server routines. 

mtb:hc-chunk-item string from &optional to Function 

Returns a substring of string containing items from to to, or the one item from. 
Similar to HyperTalk's item chunk expression, except mtb:hc-chunk-item is zero- 
based. Items are separated by commas. This function is useful for destructuring 
the string argument passed to XFCN server routines. 

Storage Allocation 

mtb:with-hc-zstring (var string) &body body Macro 

Allocates a Macintosh handle to hold a zstring copy of the Lisp string string, and 
binds the Lisp variable var to that handle, deallocating it when body exits. A Hy- 
perCard zstring is terminated by a zero byte, so don't send down Lisp bullet char- 
acters. The resulting handle can be passed to the several HyperCard callbacks that 
want zstring handles, such as mtb:hc-set-global. 

mtb:with-hc-eval-expr (result string) &body body Macro 

Binds result to the HyperCard evaluation of the HyperCard expression string, for 
the duration of body. This sends string to HyperCard, sends result back to Lisp, 
and deallocates the HyperCard handle when done. 

mtb:making-qd-picture (rect) &body body Macro 

Returns a Macintosh handle to a QuickDraw picture created by Lisp calls to 
QuickDraw within body. (See the section "Lisp Functions That Interface the Mac- 
intosh QuickDraw Manager" for a complete list of these functions.) Uses the 
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QuickDraw operations OpenPicture and ClosePicture around body. The picture's 
rect is rect. 

For example: 

(defun make-pi ct-file-from-i con (icon-handle pathname) 
(with-open-refnum (out pathname :permission (cconstant fsWrPerm)) 
(_SetEOF out 512) 
(let ((pict (with-rect (r 32 32) 

(making-qd-picture (r) (_ploticon r handle))))) 
(let {{err (with-handle-locked (pict) 

(_fswrite-remote out (_ptrf romhandle pict) (_gethandlesize pict))))) 
(unless (zerop err) 
(mtb: :signal-mac-os-error err)))))) 



Callbacks to HyperCard: Maclvory Glue Functions 

This section describes the Maclvory glue routines, which are used in making your 
external commands communicate with HyperCard. These "glue" routines, or call- 
backs, form an interface through which you can access HyperCard's internal rou- 
tines. The argument list for each routine describes Lisp and HyperCard parame- 
ters. HyperCard parameters are set in their own typeface. For example, in the ar- 
gument list /nsg'(string), msg is a Lisp value and string is a Macintosh value. 

Note that not all callbacks defined by HyperCard are implemented with remote 
entries. The simplest of string operations, coercions, and format conversions are 
amply handled by Symbolics Common Lisp; there is no need to call back to Hyper- 
Card. These are the unimplemented routines: 

BoolToStr 

ExtToStr 

LongToStr 

NumToHex 

NumToStr 

PasToZero 

ReturnToPas 

ScanToReturn 

ScanToZero 

StringEqual 

StringLength 

StringMatch 

StrToBool 

StrToExt 

StrToLong 

StrToNum 

ZeroToPas 



Page 1038 



mtb:hc-send-card-message msg(string) Function 

Sends a HyperCard message to the current card. Compare with mtb:hc-send-hc- 
message. HyperCard also contrasts expression evaluation with message sending. 



mtbrhc-send-hc-message msgCstrinq) Function 

Sends a HyperCard message, bypassing the normal inheritance path. Compare with 
mtb:hc-send-card-message. HyperCard also contrasts expression evaluation with 
message sending. 



mtbrhc-eval-expr exj9r(stringj Function 

HyperCard evaluates the expression and allocates a handle to hold its result. You 
probably really want to use mtbrwith-hc-eval-expr, which checks the errcode and 
deallocates the handle for you. HyperCard contrasts expression evaluation with 
message sending. 

Returns result(handle), errcode(integer-16). 



mtbrhc-zero-bytes address(Ptr), lengthfinteger-dZ) Function 

Zeros length bytes of Macintosh memory starting at address. 

mtbrhc-get-global global-name(strinq) Function 

Gets the value of HyperCard global variable. Note that you must deallocate the 
handle. 

Returns result(handle). 

vathih-C-sei-^Xohal global-name(strinq), value(Hanti,^e) Function 

Sets the value of HyperCard global variable. Note that this callback does not place 
the value into the handle for you. 

mtbrhc-get-field-by-name cardpfBool eanj, field-name(strinq) Function 

Gets the contents of the named text field (card or background, depending on 
cardp). Note that you must deallocate the handle. 

Returns result(handle). 

mtbrhc-get-field-by-num cardpfBool eanj, number(inteqe^-^Q) Function 

Gets the contents of the indexed text field (card or background, depending on the 
value of cardp). Note that you must deallocate the handle. 

Returns result(handle). 
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mtbrhc-get-field-by-id cardpfBool eanj, id(^nteger-^6) Function 

Gets the contents of the identified text field (card or background, depending on 
cardp). Note that you must deallocate the handle. 

Returns result(handle). 



mtbrhc-set-field-by-name cardpfBool eanj, name(strinq), value(Hanti,^e) Function 

Sets the contents of the named text field (card or background, depending on the 
value of cardp). Note that this callback does not place the value into the handle 
for you. 



mtbrhc-set-field-by-num cardpfBool eanj, number(inteqe^-^Q), value(Hanti,^e) Function 

Sets the contents of the indexed text field (card or background, depending on the 
value of cardp). Note that this callback does not place the value into the handle 
for you. 



mtbrhc-set-field-by-id cardpfBool eanj, idfinteger-iej, value(Hanti,^e) Function 

Sets the contents of the identified text field (card or background, depending on 
cardp). Note that this callback does not place the value into the handle for you. 



Existing Calllvory Servers 

mtbrlist-routines ignore Function 

Prints a comma-separated list of the names of all Calllvory servers. 

mtbrecho-arg string Function 

Returns string. 

mtbrbeep-some count Function 

Beeps count times. 

mtbreval-some forms Function 

Reads forms from the string forms, and evals them. The first value from each 
form becomes a value of mtbreval-some. 

mtb:command-some command-and-args Function 
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Runs the Command Processor command line command-and-args . The following Cal- 
llvory servers implement or support the behavior of the corresponding cards: 

flavor-parts 

cards-for-all-desktop-icons 

cards-for-sage-topic 

map-hack-click 

list-mugshots-starting-with 

get-mugshot-for 

get-mugshot-for-1 



Hints for Writing Calllvory Servers 

• Note that if HyperCard is stuck, there is no UI service for Genera. If the XFCN 
server is in the Debugger, HyperCard is stuck. If there is no UI service for 
Genera, you cannot type out the Debugger. Contact the Symbolics Consulting 
Group if you need assistance with this. 

• Other RFC agents, besides EMB, work, if built into the XFCN. 

• Remember to deallocate the handles HyperCard allocates for you. If you gradual- 
ly run out of HyperCard heap space, the HyperTalk function HeapSpace might 
help. In some cases HyperCard itself uses heavy dynamic memory 
allocation/deallocation. 



Example of Creating a Calllvory Server 

This simple example shows the process of adding a new Calllvory server for Lisp 
to respond to requests initiated by HyperCard. The code for the Lisp server form, 
along with four HyperTalk scripts, is distributed in the file 

SYS:EMBEDDING;MAClVORY;HYPERCARD;SPELL.LISP. 

This discussion assumes that you are familiar with using and programming both 
Genera and HyperCard. 

The distributed Hyperlvory stack and the associated HyperCard/MacIvory system 
already contain the code discussed here, so you may have to ignore various redefi- 
nition warnings. See Figure 97 with the "Spellbound" card in the Hyperlvory stack. 

You must inform HyperCard that you are authorized to write the HyperTalk 
scripts in this example. To do this: 

1. While running HyperCard, go to the Home card (choose the "Home" menu 
command). 

2. Go to the User Preferences card (choose the "Prev" menu command). 
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Spellboynd/ " 




The word: customar 


{ Spell ) 




may be spelled: 

customer 

customary 






= 


Oc^ 



Figure 97. The "Spellbound" card 

3. Click on the "Scripting" radio button. 

Now: 

1. Compile the define-xfcn-server form. 

In Genera, switch to Zmacs and compile this code. It is distributed in 

SYS:EMBEDDING;MACIVORY;HYPERCARD;SPELL.LISP. 



2. 



;;; -*- Mode: LISP; Syntax: Common-lisp; Package: USER; Base: 10 -*- 

(mtb: :def ine-xfcn-server spell-word (word) 

(setq word (string-trim ' (tfXspace tfXreturn tfXtab) word)) 
(if (zwei :word-in-dictionaries-p word (string-length word)) 
(write-line "is spelled correctly.") 
(let ((corrections (zwei :get-al 1-corrections word))) 
(cond ((null corrections) 

(write-line "is unknown and possibly misspelled.")) 
(T 
(write-line "may be spelled:") 
(mapc tt'write-line corrections)))))) 

This form returns its results to HyperCard by printing to *standard-output* 
The HyperTalk script receiving the value simply puts it into a text field. 

Find an appropriate HyperCard stack. 

You have several choices: 



• Simply use the distributed Hyperlvory stack, duplicate that stack using the 
Finder, and modify the copy. 



Page 1042 



• Open the Hyperlvory stack, use HyperCard's "Save a Copy ..." menu item, 
and modify the copy. 

• Use HyperCard to make a new stack, and manually move the stack script 
(using HyperCard) and the XFCN resource (using ResEdit or equivalent). 

3. Create a card. 

In HyperCard, use the "New Card" menu command. The new card will share 
its background with the background of the card you're looking at. 

4. Create fields "Word", "Respellings", "Errors". 

Use the "New Field" menu command. Drag the fields around to place and size 
them the way you want. Use the "Field Info" menu command to set the field 
names, which are referred to by the HyperTalk scripts. 

While you have the "Word" field open, type in its script. 

— This is just so you don't have to move your hand from kbd to mouse 
on returnlnField 

send closeField to me 

spel ITheWord 
end returnlnField 

5. Create button "Spell". 

Use the "New Button" menu command and the "Button Info" menu command. 

While you have the "Spell" button open, type in its script. 

on mouseUp 

spel ITheWord 
end mouseUp 

6. Add script for card. 

Use the "Card Info" menu command to get to the card's script window, and 
type it in. If you are tired of typing, and you are running MultiFinder, you 
could take advantage of the communication between Genera kill-ring and 
Macintosh clipboard: 

a. Switch from HyperCard to Genera. 

b. Select Zmacs and get the example code in a buffer. 

c. Mark the code and use the "Copy" command from the menu bar. 

d. Switch back to HyperCard. 
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e. Get to the card's script window. 

f. Choose the "Paste" menu command. 



on openCard 

— start off with no errors showing 

hide card field "Errors" 

— be able to start typing without selecting/killing first 

select text of card field "word" 

pass openCard 
end openCard 

on spell TheWord 

put empty into card field "Respel 1 ings" 

hide card field "Errors" 

— Hilight the Spell button to provide feedback to user while doing the work 

set the hilite of card button "Spell" to true 

— do the real work 

put Cal 1 Ivory("spel 1-word" , card field "word") into results 

— check for errors, and report them 

put Resul tError(resul ts) into card field "Errors" 

if card field "Errors" is not empty then 

put "Lisp Error:" & return before card field "Errors" 

show card field "Errors" 
else 

— unscroll from last time, perhaps 

set the scroll of card field "Respel 1 ings" to 

— show respel lings if any 

put Resul tTypeout(results) into card field "Respel 1 ings" 
end if 

— Done with work, unhilight 

set the hilite of card button "Spell" to false 
end spell TheWord 

7. Draw some ghtzy titles and so on. 

Scribble all over the card if it suits your purposes. 

8. Link to the new card with some buttons somewhere. 
This is optional, of course. 



Lisp Functions That Access the Macintosh Toolbox 
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The following tables list the Lisp functions that let you access the corresponding 
routines in the Macintosh Toolbox. The routines are grouped by Apple managers 
and listed alphabetically. The tables show you the name of a Lisp function, its ar- 
guments, and any returned values. All Lisp functions are preceded by the package 
prefix mtb:. These functions provide automatic (Macintosh) type translation. 

Note that names are given in Macintosh case style for readability, but that, in 
fact, these functions are case insensitive. 



Adb Manager 

Lisp Function 



Arguments 



Values Returned 



_ADBOp 

_ADBReInit 
_CountADBs 
_GetADBInfo 
_GetIndADB 
SetADBInfo 



(data compout buffer 

commandnum) 





(infoin address) 

(infoin devtableindex) 

(info address) 



(devicecount) 
(infoout) 
(address infoout) 



Appletalk-Manager 

No Entries defined for Appletalk-Manager. 

Color-Manager 



Lisp Function 


Arguments 




Values Returned 


_AddComp 


(compproc) 






_AddSearch 


(searchproc) 






_Color2Index 


(rgb) 




(index) 


_DelComp 


(compproc) 






_DelSearch 


(searchproc) 






_GetCTSeed 







(seed) 


_GetSubTable 


(mycolor ITABRES 


targettbl) 




_Index2Color 


(index rgbin) 




(rgbout) 


_InvertColor 


(rgbin) 




(rgbout) 


_MakeITable 


(colortab INVERSETAB res) 




_ProtectEntry 


(index protect) 






_QdError 







(qderr) 


_RealColor 


(color) 




(realp) 


_ReserveEntry 


(index reserve) 






_Re stor eEntrie s 


(srctable dsttable selection) 


(selectionout) 
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_SaveEntries 

_SetClientID 
SetEntries 



(srctable resulttable 

selection) 

(id) 

(start count atable) 



(selectionout) 



Color-Picker 



Lisp Function 



Arguments 



Values Returned 



_CMY2RGB 

_Fix2SmallFract 
_GetColor 

_HSL2RGB 
_HSV2RGB 
_RGB2CMY 
_RGB2HSL 
_RGB2HSV 
SmallFract2Fix 



(ccolor rcolor) 

(f) 

(where prompt incolor 

outcolor) 

(hcolor rcolor) 

(hcolor rcolor) 

(rcolor ccolor) 

(rcolor hcolor) 

(rcolor hcolor) 

(s) 



(rcolorout) 

(s) 

(normalexitp 

colorout) 

(rcolorout) 

(rcolorout) 

(ccolorout) 

(hcolorout) 

(hcolorout) 

(f) 



Color-Quickdraw 



Lisp Function 



Arguments 



Values Returned 



_AllocCursor 

_BackPixPat 

CalcCMask 



_CharExtra 
_CloseCPort 
_CopyPixMap 
_CopyPixPat 
_DisposCCursor 
_DisposCIcon 
_DisposCTable 
_DisposPixMap 
_DisposPixPat 
_FillCArc 
_FillCOval 
_FillCPoly 
_FillCRect 
_FillCRgn 
FillCRoundRect 





(ppat) 

(srcbits dstbits srcrect 

dstrect seedrgb matchproc 

matchdata) 

(extra) 

(port) 

(srcpm dstpm) 

(srcpp dstpp) 

(crsrhndle) 

(theicon) 

(ctable) 

(pm) 

(ppat) 

(r startangle arcangle ppat) 

(r ppat) 

(poly ppat) 

(r ppat) 

(rgn ppat) 

(r ovwd ovht ppat) 
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_GetBackColor 


(color) 


(colorout) 


_GetCCursor 


(crsrid) 


(crsrhndle) 


_GetCIcon 


(id) 


(theicon) 


_GetCPixel 


(h V cpix) 


(cpixout) 


_GetCTable 


(ctid) 


(ctable) 


_GetForeColor 


(color) 


(colorout) 


_GetPixPat 


(patid) 


(ppathandle) 


_HiliteColor 


(color) 




_InitCport 


(port) 




_MakeRGBPat 


(ppat mycolor) 




_NewPixMap 





(pixmaphandle) 


_NewPixPat 





(ppat) 


_OpColor 


(color) 




_OpenCport 


(port) 




_PenPixPat 


(ppat) 




_PlotIcon 


(therect theicon) 




_RGBBackColor 


(color) 




_RGBForeColor 


(color) 




_SeedCFill 


(srcbits dstbits srcrect 
dstrect seedh seedv matchproc 
matchdata) 




_SetCCursor 


(crsrhndle) 




_SetCPixel 


(h V cpix) 




_SetStdCProcs 


(cprocs) 


(newcprocs) 


Color-Toolbox 






Lisp Function 


Arguments 


Values Returned 


_CWindowStructure 


(cwindow -pointer cwindow) 


(out-window) 


_DelMCEntries 


(menuid menuitem) 




_DispMCInfo 


(menucolortable) 




_GetAuxCtl 


(thecontrol) 


(owncolortabp 
achndl) 


_GetAuxWin 


(thewindow) 


(existsp colortable) 


_GetCVariant 


(thecontrol) 


(variantnumber) 


_GetGrayRgn 





(rgn) 


_GetItemCmd 


(themene item) 


(cmdchar) 


_GetMCEntry 


(menuid menuitem) 


(mcentryptr) 


_GetMCInfo 





(mctable) 


_GetNewCWindow 


(windowid wstorage behind) 


(cwindow) 


_GetWVariant 


(whichwindow) 


(number) 


_InitProcMenu 


(mbresid) 




_MenuChoice 





(choice) 


_NewCDialog 


(dstorage boundsrect title 


(dialogptr) 
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visible procid behind 
goawayflag refcon items) 



_NewCWindow 


(wstorage boundsrect title 
visible procid behind 
goawayflag refcon) 


(cwindow) 


_PopUpMenuSelect 


(themenu top left popupitem) 


(choice) 


_SetCtlColor 


(thecontrol newcolortable) 




_SetDeskCPat 


(deskpixpat) 




_SetItemCmd 


(themene item cmdchar) 




_SetMCEntries 


(numentries menucentries) 




_SetMCInfo 


(menucolortable) 




_SetWinColor 


(thewindou! newcolortable) 




Control-Manager 






Lisp Function 


Arguments 


Values Returned 


_DisposeControl 


(thecontrol) 




_DragControl 


(thecontrol startpt limitrect 
sloprect axis) 




_DrawlControl 


(thecontrol) 




_DrawControls 


(thewindow) 




_FindControl 


(thepoint thewindow) 


(whichcontrol) 


_GetCRefCon 


(thecontrol) 


(value) 


_GetCTitle 


(thecontrol string) 


(out-title) 


_GetCtlAction 


(thecontrol) 


(actionproc) 


_GetCtlMax 


(thecontrol) 


(value) 


_GetCtlMin 


(thecontrol) 


(value) 


_GetCtlValue 


(thecontrol) 


(value) 


_GetNewControl 


(controlid thewindow) 


(thecontrol) 


_HideControl 


(thecontrol) 




HiliteControl 


(thecontrol highlight-state) 




_KillControls 


(thewindow) 




_MoveControl 


(thecontrol h v) 




_NewControl 


(thewindow boundsrect title 
visible value min max procid 
refcon) 


(thecontrol) 


_SetCRefCon 


(thecontrol value) 




_SetCTitle 


(thecontrol title) 




_SetCtlAction 


(thecontrol actionproc) 




_SetCtlMax 


(thecontrol thevalue) 




_SetCtlMin 


(thecontrol thevalue) 




_SetCtlValue 


(thecontrol thevalue) 




_ShowControl 


(thecontrol) 




_SizeControl 


(thecontrol w h) 




_TestControl 


(thecontrol thepoint) 


(part-code) 
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_TrackControl 


(thecontrol startpt 
actionproc) 


(part-code) 


_UpdtControl 


{thewindow updatergn) 




Desk Manager 






Lisp Function 


Arguments 


Values Returned 


_CloseDeskAcc 


(refnum) 




_OpenDeskAcc 


(theacc) 


(driver-ref) 


_SystemClick 


(theevent thewindow) 




_SystemEdit 


(editcmd) 


(deskaccp) 


_SystemEvent 


(theevent) 


(deskaccp) 


_SystemMenu 


(menuresult) 




_SystemTask 







Device-Manager 






Lisp Function 


Arguments 


Values Returned 


_CloseDriver 


(refnum) 




_Control 


(refnum cscode csparamptr) 




_GetDCtlEntry 


(refnum) 


(controlhandle) 


_KillIO 


(refnum) 




_OpenDriver 


(name) 


(refnum) 


_PBControl 


(completion vrefnum refnum 
code param) 




_PBKillIO 


(completion refnum) 


(param) 


_PBStatus 


(completion vrefnum refnum 
code) 


(param) 


_Status 


(refnum cscode csparamptr) 




Dialog-Manager 






Lisp Function 


Arguments 


Values Returned 


_Alert 


(alertid filterproc) 


(itemhit) 


_CautionAlert 


(alertid filterproc) 


(itemhit) 


_CloseDialog 


(thedialog) 




_CouldAlert 


(alertid) 




_CouldDialog 


(dialogid) 




_DialogSelect 


(theevent) 


(deventp thedialc 



itemhit) 
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_DisposDialog 


(thedialog) 




_DlgCopy 


(thedialog) 




_DlgCut 


(thedialog) 




_DlgDelete 


(thedialog) 




_DlgPaste 


(thedialog) 




_DrawDialog 


(thedialog) 




_ErrorSound 


(soundproc) 




_FindDItem 


(thedialog thept) 


(itemno) 


_FreeAlert 


(alertid) 




_FreeDialog 


(dialogid) 




_GetAlrtStage 





(stage) 


_GetDItem 


(thedialog itemno box) 


(itemtype 
itemhandle outbox) 


_GetIText 


(item) 


(text) 


_GetNewDialog 


(dialogid dstorage behind) 


(dialogptr) 


_HideDItem 


(thedialog itemno) 




_InitDialogs 


(resumeproc) 




_IsDialogEvent 


(theevent) 


(deventp) 


_ModalDialog 


(filterproc) 


(itemhit) 


_NewDialog 


(dstorage boundsrect title 
visible procid behind 
goawayflag refcon items) 


(dialogptr) 


_NoteAlert 


(alertid filterproc) 


(itemhit) 


_ParamText 


(paramO paraml param2 paramS) 




_ResetAlrtStage 







_SelItext 


(thedialog itemno startsel 
endsel) 




_SetDAFont 


(fontnum) 




_SetDItem 


(thedialog itemno itemtype 
itemhandle box) 




_SetIText 


(item text) 




_ShowDItem 


(thedialog itemno) 




_StopAlert 


(alertid filterproc) 


(itemhit) 


_UpdtDialog 


(thedialog updateregion) 




Disk-Driver 






Lisp Function 


Arguments 


Values Returned 


_DiskEject 


(drvnum) 




_DriveStatus 


(drvnum statusin) 


(statusout) 


_SetTagBuffer 


(buffptr) 





Disk-Initialization 
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Lisp Function 


Arguments 


_DIBadMount 


(where evtmessage) 


_DIFormat 


(drvnum) 


_DILoad 





_DIUnload 





_DIVerify 


(drvnum) 


_DIZero 


(drvnum volname) 


File-Manager 




Lisp Function 


Arguments 


_Allocate 


(refnum allocation) 


_Create 


(filename vrefnum creator 




filetype) 


-Eject 


(volname vrefnum) 


_FInitQueue 





_FlushVol 


(volname vrefnum) 


_FSClose 


(refnum) 


_FSDelete 


(filename vrefnum) 


_FSOpen 


(filename vrefnum) 


_FSRead 


(refnum count buffer) 


_FSWrite 


(refnum count buffer) 


_GetDrvQHdr 





_GetEOF 


(refnum) 


_GetFInfo 


(filename vrefnum 




fndr-info) 


_GetFPos 


(refnum) 


_GetFSQHdr 





_GetVCBQHdr 





_GetVInfo 


(drvnum) 


_GetVol 





_GetVRefNum 


(pathrefnum) 


_OpenRF 


(filename vrefnum) 


_PBAllocate 


(refnum count) 


_PBAllocContig 


(refnum count) 


_PBCatMove 


(name vrefnum newname 




newdirid dirid) 


_PBClose 


(refnum) 


_PBCloseWD 


(vrefnum) 



Values Returned 



(result) 



Values Returned 



(actual-allocation) 



(refnum) 

(result-count 

buffer-out) 

(result-count) 

(qheader) 

(logeof) 

(outcoming-fndr-info) 

(filepos) 

(qheader) 

(qheader) 

(volname vrefnum 

freebytes) 

(volname vrefnum) 

(vrefnum) 

(refnum) 

(actual-count) 

(actual-count) 
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_PBCreate 
_PBDelete 
_PBDirCreate 

_PBEject 
_PBFlushFile 
_PBFlushVol 
_PBGetCatInfo 

_PBGetEOF 
_PBGetFCBInfo 

_PBGetFInfo 

_PBGetFPos 
_PBGetVInfo 

_PBGetVol 
PBGetWDInfo 



_PBHCreate 
_PBHDelete 
_PBHGetFInfo 

_PBHGetVInfo 

_PBHGetVol 
_PBHOpen 
_PBHOpenRF 
_PBHRstFLock 
PBHSetFInfo 



_PBHSetFLock 

_PBHSetVol 

_PBLockRange 

_PBMountVol 

_PBOffline 

_PBOpen 

_PBOpenRF 

_PBOpenWD 

PBRead 



(name vrefnum version-number) 

{name vrefnum version-number) 

{name vrefnum version-number 

dirid) 

{name vrefnum) 

{refnum) 

{name vrefnum) 

{hfileinfo name vrefnum 

fdirindex dirid) 

{refnum) 

{fcbpbrec name vrefnum 

refnum fcb-index) 

{fileparam name vrefnum 

version-number fdirindex) 

{refnum) 

{volumeparam name vrefnum 

volindex) 

{name) 

{name vrefnum wdindex 

wdprocid wdvrefnum) 

{name vrefnum dirid) 
{name vrefnum dirid) 
{hfileparam name vrefnum 
fdirindex dirid) 
{hvolumeparam name vrefnum 
volindex) 
{wdpbrecname) 

{name vrefnum permission dirid) 
{name vrefnum permission dirid) 
{name vrefnum dirid) 
{name vrefnum 
finder-info dirid 
creation-date 
modification-date) 
{name vrefnum dirid) 
{name vrefnum wddirid) 
{refnum reqcount posmode 
posoffset) 
{vrefnum) 
{name vrefnum) 
{name vrefnum versnum 
permission) 

{name vrefnum versnum 
permission) 

{name vrefnum wdprocid 
wddirid) 
{vrefnum refnum buffer count 



{new-name new-dirid) 



{result-hfileinfo 

out-name) 

{eof) 

{result-fcbpbrec 

out-name) 

{result-fileparam 

out-name) 

{mark) 

{result-volumeparam 

out-name) 

{out-name vrefnum) 

{out-name out-vrefnum 

out-wdprocid 

out-wdvrefnum out-wddirid) 



{result-hfileparam 

out-name) 

{result-hvolumeparam 

out-name) 

{result-wdpbrec out-name) 

{refnum) 

{refnum) 



{result-vrefnum) 

{refnum) 

{refnum) 

{new-wdrefnum) 

{actual-count 
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_PBRename 

_PBRstFLock 
_PBSetCatInfo 
_PBSetEOF 
PBSetFInfo 



_PBSetFLock 

_PBSetFPos 

_PBSetFVers 

PBSetVInfo 



_PBSetVol 
_PBUnlockRange 

_PBUnmountVol 
_PBWrite 

.Rename 
_RstFLock 
_SetEOF 
_SetFInfo 
_SetFLock 
_SetFPos 
_SetVol 
UnmountVol 



posmode posoffset) 

(name vrefnum version-number 

new-name) 

{name vrefnum version-number) 

(in-pb name) 

(refnum eof) 

(name vrefnum version-number 

finder-info creation-date 

modification-date) 

(name vrefnum version-number) 

(refnum posmode posoffset) 

(name vrefnum version-number 

new -version-number) 

(name vrefnum creation-date 

modification-date 

volume-attributes clump-size 

backup-date sequence -number 

finder-info) 

(name vrefnum) 

(refnum reqcount posmode 

posoffset) 

(name vrefnum) 

(vrefnum refnum buffer count 

posmode posoffset) 

(oldname vrefnum newname) 

(filename vrefnum) 

(refnum logeof) 

(filename vrefnum fndr-info) 

(filename vrefnum) 

(refnum posmode posoff) 

(volname vrefnum) 

(volname vrefnum) 



out-buffer final-mark) 



(out-name) 



(new -mark) 



(actual-count 
new -mark) 



Font-Manager 



Lisp Function 



Arguments 



Values Returned 



_FMSwapFont 
_FontMetrics 
_GetFNum 
_GetFontName 
JnitFonts 
_RealFont 
_SetFontLock 
_SetFractEnable 
SetFScaleDisable 



(inrec) 

(themetrics) 

(fontname) 

(fontnum) 



(fontnum size) 

(lockp) 

(fractp) 

(disablep) 



(outrecptr) 
(thenewmetrics) 
(thenum) 
(name) 

(realp) 



Graphics-Devices 
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Lisp Function 



Arguments 



Values Returned 



_DisposGDevice 
_GetDeviceList 
_GetGDevice 
_GetMainDevice 
_GetMaxDevice 
_GetNextDevice 
JnitGDevice 
_NewGDevice 
_SetDeviceAttribute 
_SetGDevice 
TestDeviceAttribute 



(gdhandle) 







(globalrect) 

(gdrefnum mode gdh) 

(refnum mode) 

(gdh attribute value) 

(gdh) 

(curdevice attribute) 



(gdhandle) 
(gdhandle) 
(gdhandle) 
(gdhandle) 
(gdhandle) 

(gdhandle) 



(value) 



International-Utiiities 



Lisp Function 


Arguments 


Values Returned 


_IUCompString 


(astr bstr) 


(result) 


_IUDatePString 


(datetime form intlparam) 


(result) 


_IUDateString 


(datetime form) 


(result) 


_IUEqualString 


(astr bstr) 


(result) 


JUGetlntl 


(theid) 


(irhandle) 


_IUMagIDString 


(aptr bptr alen blen) 


(result) 


_IUMagString 


(aptr bptr alen blen) 


(result) 


_IUMetric 





(metricp) 


JUSetlntl 


(refnum theid intlparam) 




JUTimePString 


(datetime wantseconds 
intlparam) 


(result) 


JUTimeString 


(datetime wantseconds) 


(result) 


List Manager 






Lisp Function 


Arguments 


Values Returned 


_LActivate 


(act Ihandle) 




_LAddColumn 


(count column Ihandle) 


(firstcolumnno) 


_LAddRow 


(count rownum Ihandle) 


(firstrownum) 
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LAddToCell 


{dataptr datalen thecell 
Ihandle) 




LAutoScroU 


(Ihandle) 




LCellSize 


(csize Ihandle) 




LClick 


ipt modifiers Ihandle) 


(doubleclickp) 


LClrCell 


(thecell Ihandle) 




LDelColumn 


(count column Ihandle) 




LDelRow 


(count rownum Ihandle) 




LDispose 


(Ihandle) 




LDoDraw 


(drawit Ihandle) 




LDraw 


(thecell Ihandle) 




LFind 


(thecell Ihandle) 


(offset len) 


LGetCell 


(dataptr datalen thecell 
Ihandle) 




LGetSelect 


(next thecellin Ihandle) 


(selectedp thecellout) 


LLastClick 


(Ihandle) 


(lastcell) 


LNew 


(rvieu! databounds csize 
theproc thewindow drawit 
hasgrow scrollhoriz 
scrollvert) 


(listhandle) 


LNextCell 


(hnext vnext thecellin 
Ihandle) 


(cellsleftp thecellout) 


LRect 


(cellrectin thecell Ihandle) 


(cellrectout) 


LScroU 


(dcols drows Ihandle) 




LSearch 


(dataptr datalen searchproc 
thecellin Ihandle) 


(foundp thecellout) 


LSetCell 


(dataptr datalen thecell 
Ihandle) 




LSetSelect 


(setit thecell Ihandle) 




LSize 


(listwidth listheight Ihandle) 




LUpdate 


(thergn Ihandle) 





Macintalk Manager 



Lisp Function 


Arguments 


_MacinTalk 


(thespeech phonemes) 


_Reader 


thespeech english 




phoneticoutput 




macintalk _refnum) 


_SpeechOff 


(thespeech) 


_SpeechOn 


(exceptions-file) 


_SpeechPitch 


(thespeech thepitch themode) 


_SpeechRate 


(thespeech therate) 



Values Returned 



(thespeech file-refnum) 
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Memory Manager 






Lisp Function 


Arguments 


Values Returned 


_ApplicZone 





(appliczoneptr) 


_BlockMove 


(sourceptr destptr bytecount) 




_CompactMem 


(cbneeded) 


(cbytesavail) 


_DisposHandle 


(h) 




_DisposPtr 


(p) 




_EmptyHandle 


(h) 




_FreeMem 





(freespace) 


_GetApplLimit 





(myptr) 


_GetHandleSize 


(h) 


(handlesize) 


_GetPtrSize 


(p) 


(ptrsize) 


_GetZone 





(currentzonethz) 


_GZSaveHnd 





iprotectedhandle) 


_HandleZone 


(h) 


(zoneptr) 


_HClrRBit 


(h) 




_HGetState 


(h) 


(state) 


_HLock 


(h) 




_HNoPurge 


(h) 




_HPurge 


(h) 




_HSetRBit 


(h) 




_HSetState 


(h state) 




_HUnlock 


(h) 




_InitApplZone 







_InitZone 


(pgrowzone cmoremasters 
limitptr startptr) 




_MaxApplZone 







_MaxBlock 





(maxcb) 


_MaxMem 





(bytesavail 
zonegrowth) 


_MemError 





(err) 


_MoreMasters 







_MoveHHi 


(H) 




_NewEmptyHandle 





(newhandle) 


_NewHandle 


(logicalsize) 


(newhandle) 


_NewPtr 


(logicalsize) 


(newptr) 


_PtrFromHandle 


(h) 


(pntr) 


_PtrZone 


(p) 


(zoneptr) 


_PurgeMem 


(cbneeded) 




_PurgeSpace 





(total contig) 


_Read-Opaque- 






Byte s-Fr om-Handle 


(h nbytes buffer) 


(buffer-out) 


_Read-Opaque- 






Bytes-From-Pointer 


(ptr nbytes buffer) 


(buffer-out) 


_ReallocHandle 


(h logicalsize) 
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_RecoverHandle 


(p) 


(handle) 


_ResrvMem 


(cbneeded) 




_SetApplBase 


(startptr) 




_SetApplLimit 


(zonelimit) 




_SetGrowZone 


(growzone) 




_SetHandleSize 


(h newsize) 




_SetPtrSize 


(p newsize) 




_SetZone 


(hz) 




_StackSpace 





(space) 


_SystemZone 





(systemzoneptr) 


_TopMem 





(topmem) 


_Write-Opaque- 






Bytes-Into-Handle- 


(h nbytes buffer) 




_Write-Opaque- 






Bytes-Into-Pointer 


(ptr nbytes buffer) 




Menu Manager 






Lisp Function 


Arguments 


Values Returned 


_AddResMenu 


(themenu thetype) 




_AppendMenu 


(themenu data) 




_CalcMenuSize 


(themenu) 




_CheckItem 


(themenu item checked) 




_ClearMenuBar 







_CountMItems 


(themenu) 


(result) 


_DeleteMenu 


(menuid) 




_DelMenuItem 


(themenu item) 




_DisableItem 


(themenu item) 




_DisposeMenu 


(themenu) 




_DrawMenuBar 







_EnableItem 


(themenu item) 




_FlashMenuBar 


(menuid) 




_GetItem 


(themenu item itemstring) 


(result-itemstring) 


_GetItemIcon 


(themenu item) 


(result) 


_GetItemMark 


(themenu item) 


(result) 


_GetItemStyle 


(themenu item) 


(result) 


_GetMenu 


(resourceid) 


(menu) 


_GetMenuBar 





(mbar) 


_GetMHandle 


(menuid) 


(result) 


_GetNewMBar 


(menubarid) 


(mbar) 


_HiliteMenu 


(menuid) 




_InitMenus 







_insertmenu 


(themenu beforeid) 




_insertresmenu 


(themenu thetype afteritem) 




_InsMenuItem 


(themenu itemstring afteritem) 




_MenuKey 


(ch) 


(menu&item) 
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_MenuSelect 
_NewMenu 
_SetItem 
_SetItemIcon 
_SetItemMark 
_SetItemStyle 
_SetMenuBar 
SetMenuFlash 



(startpt) 

{menuid menutitle) 

{themenu item itemstring) 

{themenu item icon) 

{them,enu item, m,arkchar) 

{them,enu item, chstyle) 

(m,enulist) 

(count) 



(menu&item) 
(menu) 



OS-Notification iVIanager 



Lisp function 
_NMInstall 
NMRemove 



Arguments 

(nmReqPtr QElemPtr) 
(nmReqPtr QelemPtr) 



Value Returned 

OSErr 

OsErr 



OS-Event Manager 



Lisp Function 



Arguments 



Values Returned 



_FlushEvents 
_GetEvQHdr 
_GetOSEvent 
_OSEventAvail 
_PostEvent 
_PPostEvent 
SetEventMask 



(eventmask stopmask) 



(eventmask theeventin) 

(eventmask theeventin) 

(eventcode eventmsg) 

(eventcode eventmsg) 

(eventmask) 



(queue-header-ptr) 
(eventp theeventout) 
(eventp theeventout) 

(qelptr) 



OS-Utiilties Manager 



Lisp Function 


Arguments 


Values Returned 


_Date2Secs 


(date) 


(sees) 


_Delay 


(numticks) 


(finalticks) 


_Dequeue 


(qentry thequeue) 




_Enqueue 


(qentry thequeue) 




_Environs 





(rom machine) 


_EqualString 


(astr bstr casesens diacsens) 


(equalp) 


_GetDateTime 





(sees) 


_GetMMUMode 





(mode) 


_GetSysPPtr 





(syspptr) 


_GetTime 


(datein) 


(dateout) 


_GetTrapAddress 


(trapnum) 


(trapaddr) 


_HandAndHand 


(ahndl bhndl) 




_HandToHand 


(handlein) 


(handleout) 


_InitUtil 
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_NgetTrapAddress 


(trapnum traptype) 


(trapaddr) 


_NSetTrapAddress 


(trapaddr trapnum traptype) 




_PtrAndHand 


(pntr hndl size) 




_PtrToHand 


(srcptr size) 


(newhandle) 


_PtrToXHand 


(srcptr dsthndl size) 




_ReadDateTime 





(sees) 


_RelString 


{astr bstr casesens diacsens) 


(answer) 


_Re start 







_Restorea5 







_Secs2Date 


(sees datein) 


(dateout) 


_SetDateTime 


(sees) 




_SetTime 


(date) 




_SetTrapAddress 


(trapaddr trapnum) 




_SetUpA5 







_StripAddress 


(theaddress) 


(strippedaddr) 


_SwapMMUMode 


(newmode) 


(oldmode) 


_SysBeep 


(duration) 




_UprString 


(stringin diacsens) 


(stringout) 


_WriteParam 







Palette Manager 






Lisp Function 


Arguments 


Values Returm 


_ActivatePalette 


(srcwindow) 




_AnimateEntry 


(dstwindow dstentry srcrgb) 




_AnimatePalette 


(dstwindow srcctab srcindex 
dstentry dstlength) 




_CTab2Palette 


(srcctab dstpalette srcusage 
srctolerance) 




_DisposePalette 


(srcpalette) 




_GetEntryColor 


(srcpalette srcentry dstrgbin) 


(rgbout) 


_GetEntryUsage 


(srcpalette srcentry) 


(dstusage 
dsttolerance) 


_GetNewPalette 


(paletteid) 


(palettehndl) 


_GetPalette 


(srcwindow) 


(palettehndl) 


_InitPalettes 







_NewPalette 


(entries srccolors srcusage 
srctolerance) 


(palettehndl) 


_Palette2CTab 


(srcpalette destctab) 




_PmBackColor 


(dstentry) 




_PmForeColor 


(dstentry) 




_SetEntryColor 


(dstpalette dstentry srcrgbin) 




_SetEntryUsage 


(dstpalette dstentry srcusage 
srctolerance) 




_SetPalette 


(dstwindow srcpalette 





Printing IVlanager 
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cupdates) 



Lisp Function 

_PrClose 
_PrCloseDoc 
_PrClosePage 
_PrCtlCall 

_PrDrvr Close 

_PrDrvrDce 

_PrDrvrOpen 

_PrDrvrVers 

_PrError 

_PrGeneral 

_PrintDefault 

_PrJobDialog 

_PrJobMerge 

_PrOpen 

_PrOpenDoc 

_PrOpenPage 

_PrPicFile 

_PrSetError 

_PrStlDialog 

PrValidate 



Arguments 



(pprport) 

(pprport) 

(iwhichctl Iparaml lparam2 

IparamS) 



( 

( 

( 

( 

(pdata) 

(hprint) 

(hprint) 

(hprintsrc hprintdst) 



(hprint pprport piobuf) 

(pprport ppageframe) 

(hprint pprport piobuf 

pdevbuf prstatus) 

(err) 

(hprint) 

(hprint) 



Values Returned 



(version) 
(error) 



(comfirmedp) 

(theport) 
(newprstatus) 



(comfirmedp) 
(notvalidp) 



Quici<Draw IVlanager 



Lisp Function 


Arguments 


Values Returned 


_AddPt 


(srcptl srcpt2) 


(outpt) 


_BackColor 


(color) 




_BackPat 


(pat) 




_CalcMask 


(srcptr dstptr srcrow dstrow 
height words) 




_CharWidth 


(ch) 


(width) 


_ClipRect 


(r) 




_ClosePicture 







_ClosePoly 







_ClosePort 


(port) 




_CloseRgn 


(dstrgn) 
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ColorBit 


(whichbit) 




CopyBits 


(srcbits dstbits srcrect 
dstrect mode maskrgn) 




CopyMask 


(srcbits maskbits dstbits 
srcrect maskrect dstrect) 




CopyRgn 


(srcrgn dstrgn) 




Difffign 


(srcrgna srcrgnb dstrgn) 




DisposeRgn 


(rgn) 




DrawChar 


ich) 




DrawPicture 


(mypicture dstrect) 




DrawString 


(s) 




DrawText 


(textbuf firstbyte bytecount) 




EmptyRect 


(r) 


(emptyp) 


EmptyRgn 


(rgn) 


(emptyp) 


EqualPt 


(ptl pt2) 


(equalp) 


EqualRect 


(recti rect2) 


(equalp) 


EqualRgn 


(rgna rgnb) 


(equalp) 


EraseArc 


(r startangle arcangle) 




EraseOval 


(r) 




ErasePoly 


(poly) 




EraseRect 


(r) 




EraseRgn 


(rgn) 




EraseRoundRect 


(r ovalwidth ovalheight) 




FillArc 


(r startangle arcangle pat) 




FillOval 


(r pat) 




FillPoly 


(poly pat) 




FillRect 


(r pat) 




FillRgn 


(rgn pat) 




FillRoundRect 


(r ovalwidth ovalheight pat) 




ForeColor 


(color) 




FrameArc 


(r startangle arcangle) 




FrameOval 


(r) 




FramePoly 


(poly) 




FrameRect 


(r) 




FrameRgn 


(rgn) 




FrameRoundRect 


(r ovalwidth ovalheight) 




GetClip 


(rgn) 




GetFontlnfo 


(info) 


(out-info) 


GetPen 





(outpt) 


GetPenState 


(pnstate) 


(outpnstate) 


GetPixel 


(h v) 


(onp) 


GetPort 





(outport) 


GlobalToLocal 


(pt) 


(localpt) 


GrafDevice 


(device) 




HideCursor 







HidePen 







InitCursor 







InitGraf 
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.InitPort 


(port) 




.InsetRect 


(r dh dv) 


(outrect) 


.InsetRgn 


(rgn dh dv) 




.InvertArc 


(r startangle arcangle) 




.InvertOval 


(r) 




.InvertPoly 


(poly) 




.InvertRect 


(r) 




.InvertRgn 


(rgn) 




.InvertRoundRect 


(r ovalwidth ovalheight) 




.KillPicture 


(mypicture) 




.KillPoly 


(poly) 




Line 


(dh dv) 




LineTo 


(h v) 




LocalToGlobal 


(pt) 


(globalpt) 


MapPoly 


(poly srcrect dstrect) 




MapPt 


(pt srcrect dstrect) 


(outpt) 


MapRect 


(r srcrect dstrect) 


(newrect) 


MapRgn 


(rgn srcrect dstrect) 




MeasureText 


(count textaddr charlocs) 




Move 


(dh dv) 




MovePortTo 


(leftglobal topglobal) 




MoveTo 


(h V) 




NewRgn 





(rgn) 


.ObscureCursor 







OffsetPoly 


(poly dh dv) 




OffsetRect 


(r dh dv) 


(outrect) 


OffsetRgn 


(rgn dh dv) 




OpenPicture 


(picframe) 


(pichandle) 


.OpenPoly 





(handle) 


.OpenPort 


(port) 




OpenRgn 







PaintArc 


(r startangle arcangle) 




PaintOval 


(r) 




PaintPoly 


(poly) 




PaintRect 


(r) 




PaintRgn 


(rgn) 




PaintRoundRect 


(r ovalwidth ovalheight) 




PenMode 


(mode) 




PenNormal 







PenPat 


(pat) 




PenSize 


(width height) 




PicComment 


(kind datasize datahandle) 




PortSize 


(width height) 




Pt2Rect 


(ptl pt2 dstrect) 


(outrect) 


PtInRect 


(pt r) 


(in_rectj)) 


PtInRgn 


(pt rgn) 


(inrgnp) 


PtToAngle 


(r PT) 


(angle) 


Random 





(random) 
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RectlnRgn 


(r rgn) 


(inrgnp) 


RectRgn 


(rgn R) 




ScalePt 


(pt srcrect dstrect) 


(outpt) 


ScroURect 


(r dh dv updatergn) 




SectRect 


(srcl src2 dstrect) 


(intersect-p outrect) 


SectRgn 


(srcrgna srcrgnb dstrgn) 




SeedFill 


(srcptr dstptr srcrow dstrow 
height words seedh seedv) 




SetClip 


{rgn) 




SetCursor 


(crsrptr) 




SetCursorFromHandle 


(crsrhandle) 


SetEmptyRgn 


(rgn) 




SetOrigin 


(h v) 




SetPenState 


(pnstate) 




SetPort 


(port) 




SetPortBits 


(bm) 




SetPt 


(h v) 


(outpt) 


SetRect 


(r left top right bottom) 


(outrect) 


SetRectRgn 


(rgn left top right bottom) 




SetStdProcs 


(procs) 


(outprocs) 


ShowCursor 







ShowPen 







SpaceExtra 


(extra) 




StdArc 


(verb r startangle arcangle) 




StdBits 


(srcbits srcrect dstrect mode 


(newsrcbits 




maskrgn) 


newsrcrect 
newdstrect) 


StdComment 


(kind datasize datahandle) 




StdGetPic 


(dataptr bytecount) 




StdLine 


(newpt) 




StdOval 


(verb r) 




StdPoly 


(verb poly) 




StdPutPic 


(dataptr bytecount) 




StdRect 


(verb r) 




StdRgn 


(verb rgn) 




StdRRect 


(verb r ovalwidth ovalheight) 




StdText 


(bytecount textbuf numer 
denom) 




StdTxMeas 


(bytecount textaddr numer 


(width newnumer 




denom info) 


newdenom newfontinfo) 


StringWidth 


(s) 


(width) 


StuffHex 


(thingptr s) 




SubPt 


(srcptl srcpt2) 


(outpt) 


TextFace 


(face) 




TextFont 


(font) 




TextMode 


(mode) 




TextSize 


(size) 




TextWidth 


(textbuf firstbyte 


(width) 
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_UnionRect 
_UnionRgn 
_XorRgn 



bytecount) 
(srcl src2 dstrect) 
(srcrgna srcrgnb dstrgn) 
(srcrgna srcrgnb dstrgn) 



(outrect) 



Resource Manager 



Lisp Function 


Arguments 


Values Returned 




_AddResource 


(thedata thetype theid name) 






_ChangedResource 


(theresource) 






_CloseResFile 


(refnum) 






_CountlResources 


(thetype) 


(result) 




_CountlTypes 





(result) 




_CountResources 


(thetype) 


(result) 




_CountTypes 





(result) 




_CreateResFile 


(name) 






_CurrentResLoad 





(current) 




_CurResFile 





(result) 




_DetachResource 


(theresource) 






_GetlIndResource 


(thetype index) 


(result) 




_GetlIndType 


(index) 


(result) 




_GetlNamedResource 


(thetype name) 


(result) 




_GetlResource 


(thetype theid) 


(result) 




_GetIndResource 


(thetype index) 


(result) 




_GetIndType 


(index) 


(result) 




_GetNamedResource 


(thetype name) 


(result) 




_GetResAttrs 


(theresource) 


(result) 




_GetResFileAttrs 


(refnum) 


(result) 




_GetResInfo 


(theresource name) 


(theid thetype out- 


name) 


_GetResource 


(thetype theid) 


(result) 




_HomeResFile 


(theresource) 


(result) 




_InitResources 





(result) 




_LoadResource 


(theresource) 






_MaxSizeRsrc 


(theresource) 


(result) 




_OpenResFile 


(name) 


(result) 




_OpenRFPerm 


(filename vrefnum 
permission) 


(result) 




_ReleaseResource 


(theresource) 






_ResError 





(result) 




_RGetResource 


(thetype theid) 


(rhandle) 




_RmveResource 


(theresource) 






_RsrcMapEntry 


(theresource) 


(result) 




_RsrcZoneInit 









_SetResAttrs 


(theresource attrs) 






_SetResFileAttrs 


(refnum attrs) 
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_SetResInfo 
_SetResLoad 
_SetResPurge 
_SizeResource 
_UniquelID 
_UniqueID 
_UpdateResFile 
_UseResFile 
WriteResource 



(theresource theid name) 

{load) 

{install) 

{theresource) 

{thetype) 

{thetype) 

{refnum) 

{refnum) 

{theresource) 



{result) 
{result) 
{result) 



Scrap-Resource Manager 

Lisp Function Arguments 



Values Returned 



_GetScrap 


{hdest thetype) 


{offset) 


_GetScrapStuff 


{scrapstuff) 


{newstuff) 


_InfoScrap 





{scrapstuffptr) 


_LoadScrap 


{) 




_PutScrap 


{length thetype source) 




_UnloadScrap 


{) 




_ZeroScrap 


{) 




Script Manager 






Lisp Function 


Arguments 


Values Returned 


_Char2Pixel 


{textbuf textlen slop 
offset direction) 


{pixelwidth) 


_CharByte 


{textbuf textoffset) 


{chartype) 


_CharType 


{textbuf textoffset) 


{chartype) 


_DrawJust 


{textptr textlength slop) 




_FindWord 


{textptr textlength offset 
leftside breaks offsetsin) 


{offsetsout) 


_Font2Script 


{fontnumber) 


{scriptcode) 


_FontScript 





{scriptcode) 


_GetAppFont 





{fontnum) 


_GetDefFontSize 


{) 


{size) 


_GetEnvirons 


{verb) 


{param) 


_GetMBarHeight 





{height) 


_GetScript 


{script verb) 


{param) 


_GetSysFont 





{fontnume) 


_GetSysJust 


{) 


{just) 


HiliteText 


{textptr textlength 
firstoffset secondoffset 
offsetsin) 


{offsetsout) 


_IntlScript 





{scriptcode) 


_KeyScript 


{scriptcode) 




_MeasureJust 


{textptr textlength slop 





Page 1065 





charlocs) 




_Pixel2Char 


(textbuf textlen slop 
pixelwidth) 


{offset leftside-p) 


_SetEnvirons 


{verb param) 




_SetScript 


{script verb param) 




_SetSysJust 


{newjust) 




_Transliterate 


{srchandle dsthandle target 
srcmask) 


{result) 


SCSI Manager 






Lisp Function 


Arguments 


Values Returned 


_SCSICmd 


{buffer count) 




_SCSIComplete 


{wait) 


{stat message) 


_SCSIGet 







_SCSImsgin 


{) 


{message) 


_SCSIMsgOut 


{message) 




_SCSIRBlind 


{tibptr) 




_SCSIRead 


{tibptr) 




_SCSIReset 







_SCSIselatn 


{targetid) 




_SCSISelect 


{targetid) 




_SCSIStat 


{) 


{bits) 


_SCSIWBlind 


{tibptr) 




_SCSIWrite 


{tibptr) 





Segment-Loader Manager 



Lisp Function 



Arguments 



Values Returned 



_ClrAppFiles 

_CountAppFiles 

_ExitToShell 

_GetAppFiles 

_GetAppParms 

_UnloadSeg 



{index) 





{index thefile) 



{routineaddr) 



{message count) 

{thefileout) 
{name aprefnum 
apparam) 



Serial-Driver Manager 



Lisp Function 



Arguments 



Values Returned 



_RAMSDClose 
_RAMSDOpen 



{whichport) 
{whichport) 
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_SerClrBrk 


(refnum) 




_SerGetBuf 


(refnum) 


(count) 


_SerHShake 


(refnum flags) 




_SerReset 


(refnum serconfig) 




_SerSetBrk 


(refnum) 




_SerSetBuf 


(refnum serbptr serblen) 




_SerStatus 


(refnum serstatin) 


(serstatout) 


Slot Manager 






Lisp Function 


Arguments 


Values Returned 


JnitPRAMRecs 







JnitSDeclMgr 







_InitsRsrcTable 







_sCalcsPointer 


(spspointer spoffsetdata 
spbytelanes) 




_sCalcStep 


(spspointer spbytelanes 
spflags) 


(spresult) 


_sCardChanged 


(spslot) 


(spresult) 


_sCkCardStatus 


(spslot) 


(spresult) 


_sdeleteSRTRec 


(spslot spid spextdev) 




_sExec 


(spspointer spid spsexecpblk) 


(spresult) 


_sFindDevBase 


(spslot spid) 


(spresult) 


_sFindsInfoRecPtr 


(spslot) 


(spresult) 


_sFindsRsrcPtr 


(spslot spid) 


(spspointer) 


_sFindStruct 


(spid spspointer) 


(new-spspointer spbytelanes) 


_sGetBlock 


(spspointer spid) 


(spresult spoffsetdata 
spbytelanes spsize spflags) 


_sGetcString 


(spspointer spid) 


(spresult spoffsetdata 
spbytelanes spsize spflags) 


_sGetDriver 


(spslot spid spextdev 
spsexecpblk) 


(spresult spflags spsize) 


_SNextsRsrc 


(spslot spid spextdev) 


(new-spslot new-spid 



_sNextTypesRsrc 



(spslot spid spextdev sptbmask 
spcategory spctype spdrvrsw 
spdrvrhw sphwdev) 



new-spextdev spspointer 
sprefnum spioreserved 
spcategory spctype spdrvrsw 
spdrvrhw sphwdev) 
(new-spslot new-spid 
new-spextdev spspointer 
sprefnum spioreserved 
new -spcategory new-spctype 
new-spdrvrsw new-spdrvrhw 
new-sphwdev) 
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_sOffsetData 


(spspointer spid) 


(spoffsetdata spbytelanes 
spresult spflags) 


_sPrimaryInit 


(spflags) 




_sPtrToSlot 


(spspointer) 


(spslot) 


_sPutPRAMRec 


(spslot spspointer) 




_sReadByte 


(spspointer spid) 


(spresult spoffsetdata 
spbytelanes) 


_sReadDrvrName 


(spslot spid spresult) 


(spsize spspointer) 


_sReadFHeader 


(spslot spresult) 


(spspointer spbytelanes spsize 
spoffsetdata) 


_sReadInfo 


(spslot spresult) 


(spsize) 


_sReadLong 


(spspointer spid) 


(spresult spoffsetdata 
spbytelanes spsize) 


_sReadPBSize 


(spspointer spid spflags) 


(spsize spbytelanes spresult) 


_sReadPRAMRec 


(spslot spresult) 


(spsize) 


_sReadStruct 


(spspointer spsize spresult) 


(spbytelanes) 


_sReadWord 


(spspointer spid) 


(spresult spoffsetdata 
spbytelanes) 


_sRsrcInfo 


(spslot spid spextdev) 


(spspointer spioreserved 
sprefnum spcategory spctype 
spdrvrsw spdrvrhw sphwdev) 


_sSearchSRT 


(spslot spid spextdev spflags 
spspointer) 




_sUpdateSRT 


(spslot spid spextdev sprefnum 


(spspointer spflags spsize 




spioreserved) 


spresult) 


Sound Manager 






Lisp Function 


Arguments 


Values Returned 


_GetSoundVol 





(level) 


_SetSoundVol 


(level) 




_SndAddModifier 


(chan modifier id init) 




_SndControl 


(id cmd) 


(cmdout) 


_SndDisposeChannel (chan quitnow) 




_SndDoCommand 


(chan cmd nowait) 




_SndDoImmediate 


(chan cmd) 




_SndNewChannel 


(chan synth init userroutine) (newchan) 


_SndPlay 


(channel sndhdl async) 




_SoundDone 





(donep) 


_StartSound 
_StopSound 


(synthrec numbytes 
completionrtn) 
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Standard-File-Package Manager 



Lisp Function 


Arguments 


Values Returned 


_SFGetFile 


(where prompt filefilter 
numtypes typelist 
dialoghook reply) 


(replyout) 


_SFPGetFile 


{where prompt filefilter 
numtypes typelist 
dialoghook reply dlgid 
filterproc) 


(replyout) 


_SFPPutFile 


(where prompt origname 
dlghook reply dlgid 
filterproc) 


(replyout) 


_SFPutFile 


{where prompt origname 
dlghook reply) 


(replyout) 



System-Misc Manager 



Lisp Function 


Arguments 


Values Returned 


_DTInstall 


(dttaskptr) 




_InitAllPacks 







_InitPack 


(packid) 




_InsTime 


(tmtaskptr) 




_NumToString 


(thenum) 


(thestring) 


_PrimeTime 


(tmtaskptr count) 




_RmvTime 


(tmtaskptr) 




_ShutDwnInstall 


(shutdwnproc flags) 




_ShutDwnPower 







_ShutDwnRemove 


(shutdwnproc) 




_ShutDwnStart 







_StringToNum 


(thestring) 


(thenum) 


_SysEnvirons 


(versionRequested) 


(theWorld) 


_SysError 


(errorcode) 




TextEdit Manager 






Lisp Function 


Arguments 


Values Returned 


_GetStylHandle 


(hte) 


(stylehandle) 


_GetStylScrap 


(hte) 




_SetClikLoop 


(clikproc hte) 




_SetStylHandle 


(thehandle hte) 
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_SetWordBreak 

_TEActivate 

_TEAutoView 

_TECalText 

_TEClick 

_TECopy 

_TECut 

_TEDeactivate 

_TEDelete 

_TEDispose 

_TEFromScrap 

_TEGetHeight 

_TEGetOffset 

_TEGetPoint 

_TEGetScrapLen 

_TEGetStyle 

_TEGetText 

_TEIdle 

_TEInit 

_TEInsert 

_TEKey 

_TENew 

_TEPaste 

_TEPinScroll 

_TEReplaceStyle 

_TEScrapHandle 
_TEScroll 
_TESelView 
_TESetJust 
_TESetScrapLen 
_TESetSelect 
_TESetStyle 
_TESetText 
_TEStylInsert 
_TEStylNew 
_TEStylPaste 
_TEToScrap 
_TEUpdate 
TextBox 



(wbrkproc hte) 

(hte) 

(autoview hte) 

(hte) 

(pt extend hte) 

(hte) 

(hte) 

(hte) 

(hte) 

(hte) 



{endline startline hte) 

{pt hte) 

{offset hte) 



{offset thestyle hte) 

{hte) 

{hte) 



{text length hte) 

{key hte) 

{destrect viewrect) 

{hte) 

{dh dv hte) 

{mode oldstyle newstyle 

redraw hte) 



{dh dv hte) 

{hte) 

{just hte) 

{length) 

{selstart selend hte) 

{mode newstyle redraw hte) 

{text length hte) 

{text length hst hte) 

{destrect viewrect) 

{hte) 



{rupdate hte) 

{text length box just) 



{height) 

{offset) 

{pt) 

{length) 

{style lineheight fontascent) 

{charshandle) 



{handle) 



{scraphandle) 



{handle) 



Toolbox-Event Manager 

Lisp Function Arguments 



Values Returned 



.Button 
EventAvail 





{eventmask theevent) 



{downp) 

{handle-event-p nextevent) 



Page 1070 



GetCaretTime 





(carettime) 


GetDblTime 





(dbltime) 


GetKeys 


(keymapin) 


(keymapout) 


GetMouse 





(mouseloc) 


GetNextEvent 


(eventmask theevent) 


(handle-event-p nextevent) 


KeyTrans 


{transdata keycode) 


{result state) 


StillDown 





(stilldownp) 


TickCount 





(tickcount) 


WaitMouseUp 





(stilldownp) 



Toolbox-Utilities Manager 



Asp Function 


Arguments 


Values Returned 


AngleFromSlope 


(slope) 


(angle) 


BitAnd 


(valuel value2) 


(result) 


BitClr 


(byteptr bitnum) 




BitNot 


(value) 


(result) 


BitOr 


(valuel value2) 


(result) 


BitSet 


(byteptr bitnum) 




BitShift 


(value count) 


(result) 


BitTst 


(byteptr bitnum) 


(resultp) 


BitXor 


(valuel value2) 


(result) 


DeltaPoint 


(pta ptb) 


(longresult) 


FixMul 


(a b) 


(answer) 


FixRatio 


(numer denom) 


(fixed) 


FixRound 


(X) 


(int) 


GetCursor 


(cursorid) 


(chandle) 


Getlcon 


(iconid) 


(iconhandle) 


GetlndPattern 


(thepattern patlistid index) 


(thepatternout) 


GetlndString 


(stringin strlistid index) 


(stringout) 


.GetPattern 


(patid) 


(phandle) 


GetPicture 


(picid) 


(phandle) 


GetString 


(stringid) 


(strhandle) 


HiWord 


(x) 


(hiword) 


LongMul 


(a b) 


(answer) 


LoWord 


(x) 


(loword) 


Hunger 


(h offset ptrl lenl ptr2 len2) 


(answer) 


NewString 


(thestring) 


(strhandle) 


PackBits 


(srcptrin dstptrin srcbytes) 


(srcptrout dstptrout) 


Plotlcon 


(therect theicon) 




.ScreenRes 





(scrnhres screenvres] 


SetString 


(h thestring) 




.ShieldCursor 


(shieldrect offsetpt) 




.SlopeFromAngle 


(angle) 


(slope) 


UnpackBits 


(srcptrin dstptrin srcbytes) 


(srcptrout dstptrout) 
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Vertical-Retrace Manager 

Lisp Function Arguments 



_AttachVBL 

_DoVBLTask 

_GetVBLQHdr 

_SlotVInstall 

_SlotVRemove 

_VInstall 

_VRemove 

Window iVIanager 

Lisp Function 

_BeginUpdate 

_BringToFront 

_CalcVis 

_CalcVisBehind 

_CheckUpdate 

_ClipAbove 

_Close Window 

_DisposeWindow 

_DragGrayRgn 

_DragWindow 

_DrawGrowIcon 

_DrawNew 

_EndUpdate 

_FindWindow 

_FrontWindow 

_GetNewWindow 

_GetWindowPic 

_GetWMgrPort 

_GetWRefCon 

_GetWTitle 

_GrowWindow 

_HideWindow 

_HiliteWindow 

_InitWindows 

_InvalRect 

_InvalRgn 

_MoveWindow 

NewWindow 



(theslot) 

(theslot) 



(vbltaskptr theslot) 

(vbltaskptr theslot) 

(vbltaskptr) 

(vbltaskptr) 



Arguments 

(thewindow) 

(window) 

(window) 

(startwindow clobberedrgn) 

(theevent) 

(window) 

(thewindow) 

(thewindow) 

(thergn startpt limitrect 

sloprect axis actionproc) 

(thewindow startpt 

boundsrect) 

(thewindow) 

(window update) 

(thewindow) 

(thepoint) 



(windowid behind) 

(thewindow) 



(thewindow) 

(thewindow in-title) 

(thewindow startpt sizerect) 

(thewindow) 

(thewindow fhilite) 



(badrect) 

(badrgn) 

(thewindow hglobal vglobal 

front) 

(boundsrect title visible 

procid behind goawayflag 



Values Returned 



(qhdrptr) 



Values Returned 



(new -event found-p) 



(point jdifference) 



(whichwindow kind) 

(window) 

(newwindow) 

(pic) 

(wport) 

(data) 

(out-title) 

(portsize) 



(newwindow) 
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refcon) 




PaintBehind 


(startwindou! clobberedrgn) 




PaintOne 


{window clobberedrgn) 




PinRect 


(therect thept) 


(nearest-point 


SaveOld 


(window) 




.SelectWindow 


(thewindow) 




.SendBehind 


(thewindow behindwindow) 




SetWindowPic 


(thewindow pic) 




SetWRefCon 


(thewindow data) 




SetWTitle 


(thewindow new-title) 




.ShowHide 


(thewindow showflag) 




.ShowWindow 


(thewindow) 




.Size Window 


(thewindow width height 
fupdate) 




TrackBox 


(thewindow thepoint partcode) 


(result) 


.TrackGoAway 


(thewindow thepoint) 


(result) 


ValidRect 


(goodrect) 




ValidRgn 


(goodrgn) 




WindowStructure 


(window -pointer window) 


(out-window) 


ZoomWindow 


(thewindow partcode front) 





Maclvory Error Conditions 

This appendix describes Maclvory error conditions. The Macintosh error name, the 
corresponding Lisp error condition and the error message are given for each error 
condition. Remote error flavors for the toolbox routines are in the macintosh- 
internals package. 

The errors are listed in alphabetical order by Macintosh error name. 

abortE rr mac-os-error-aborterr 

I/O request aborted by KilllO 



addResFai 1 ed 

AddResource failed 



mac-os-error-addresf ailed 



badBtSl pErr mac-os-error-badbtslperr 

Bad address mark (btslp) 



badChannel 



mac-os-error-badchannel 



Invalid channel queue length 



badCksmErr 



mac-os-error-badcksmerr 



Bad address mark (cksum) 



badDBtSlp mac-os-error-baddbtslp 

Bad data mark (btslp) 
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badDCksum mac-os-error-baddcksum 

Bad data mark (cksum) 

badFormat mac-os-error-badformat 

Handle to snd resource was invalid 

badMDBErr mac-os-error-badmdberr 

Bad master directory block; must reinitialize volume 

badMovErr mac-os-error-badmoverr 

Attempted to move into offspring 

badUni tErr mac-os-error-baduniterror 

Driver reference number doesn't match unit table 

bdNamE rr mac-os-error-bdnamerr 

Bad file name or volume name (perhaps zero-length) 

cantStepErr mac-os-error-cantsteperr 

Drive error (step) 

clkRdErr mac-os-error-clkrderr 

Unable to read clock 

clkWrErr mac-os-error-clkwerr 

Time written did not verify 

controlErr mac-os-error-controlerr 

Driver can't respond to this Control call 

cor Err mac-os-error-corerr 

Trap ("core routine") number out of range 

dataUerE rr mac-os-error-datavererr 

Read-verify failed 

dlnstErr mac-os-error-dinsterr 

Couldn't find driver in resource file 

dirPulErr mac-os-error-dirfulerr 

File directory full 

dirNFErr mac-os-error-dirnferr 

Directory not found 

dRemovErr mac-os-error-dremoverr 

Attempt to remove an open driver 

dskFulErr mac-os-error-dskfulerr 

All allocation blocks on the volume are full 
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dupFNErr mac-os-error-dupfnerr 

File with specified name and version number already exists 

envNotPresent mac-os-error-envnotpresent 

Sysenvirons trap not present, system file earlier than version 4.1. 

eofErr mac-os-error-eoferr 

Logical end-of-file reached during read operation 

evtNotEnb mac-os-error-evtnotenb 

Event type not designated in system event mask 

extPSErr mac-os-error-extfserr 

External file system; file-system identifier is nonzero, or path reference 
number is >1024 

fBsyE rr mac-os-error-fbsyerr 

File is busy, one or more files are open 

fLckdErr mac-os-error-flckderr 

File is locked 

fnfErr mac-os-error-fnferr 

File not found 

fnOpnErr mac-os-error-fnopnerr 

File not open 

fsDSIntErr mac-os-error-f sdsinterr 

Internal file system error 

fsRnE rr mac-os-error-f srnerr 

Problem during rename 

gfpErr mac-os-error-gfperr 

Error during GetFPos 

i 1 A b r t mac-os-error-iioabort 

I/O Error 

i MemPul 1 Err mac-os-error-imemfuUerr 

Not enough room in heap zone 

i n i 1 1 W M E r r mac-os-error-initiwmerr 

Can't initialize disk controller chip 

i E r r mac-os-error-ioerr 

I/O error 

iPrAbort mac-os-error-iprabort 

Application or user requested abort 
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i P r S a V P F i 1 mac-os-error-ipr savpf il 

Saving spool file 

memAZErr mac-os-error-memazerr 

Undocumented Memory Manager error -113 

memPullErr mac-os-error-memfuUerr 

Not enough room in heap zone 

memLockedErr mac-os-error-memlockederr 

Block is locked 

memPurErr mac-os-error-mempurerr 

Attempt to purge a locked block 

memROZErr mac-os-error-memrozerr 

operation on read-only zone 

memWZErr mac-os-error-memwzerr 

Attempt to operate on a free block 

nil Handl eErr mac-os-error-nilhandleerr 

NIL master pointer 

noAdrMkE rr mac-os-error-noadrmkerr 

Can't find an address mark 

NoDriveErr mac-os-error-nodriveerr 

Drive isn't connected 

noDtaMkErr mac-os-error-nodtamkerr 

Can't find a data mark 

noHardware mac-os-error-nohar dware 

No Hardware support for the specified synthesizer 

noMacDskErr mac-os-error-nomacdskerr 

Not a Macintosh disk; volume lacks Macintosh-format directory 

noNybErr mac-os-error-nonyberr 

Disk is probably blank 

noScrapErr mac-os-error-noscr aperr 

Desk scrap isn't initialized 

notEnoughHardware mac-os-error-notenoughhar dware 

No more channels for the specified synthesizer 

notOpenErr mac-os-error-notopenerr 

Driver isn't open 



Page 1076 



noTypeErr mac-os-error-notypeerr 

No data of the requested type 

nsDrvErr mac-os-error-nsdrverr 

No such drive; specified drive number doesn't match any number in the 
drive queue 

nsvErr mac-os-error-nsverr 

Specified volume doesn't exist 

offLinErr mac-os-error-of flinerr 

No disk in drive 

openE rr mac-os-error-openerr 

Requested read/write permission doesn't match driver's open permission 

opWrE rr mac-os-error-opwrerr 

The read/write permission of only one access path to a file can allow writing 



paramErr mac-os-error-paramerr 

Error in parameter list 

permErr mac-os-error-permerr 

Attempt to open locked file for writing 

posE rr mac-os-error-poserr 

Attempt to position before start of file 

p r I n i t E r r mac-os-error-priniterr 

Validity status is not $A8 

prWrErr mac-os-error-prwrerr 

Parameter RAM written did not verify 

qE rr mac-os-error-qerr 

Entry not in queue 

queuePull mac-os-error-queuefuU 

No room in queue 

readErr mac-os-error-readerr 

Driver can't respond to Read calls 

resFNotPound mac-os-error-resf notf ound 

Resource file not found 

resNotPound mac-os-error-resnotf ound 

Resource not found 



Page 1077 



resProbl em mac-os-error-resproblem 

Problem loading resource 

rfNumErr mac-os-error-rfnumerr 

Path reference number specifies nonexistent access path 

rmvResFai 1 ed mac-os-error-rmvresfailed 

RmveResource failed 

sectNFErr mac-os-error-sectnferr 

Can't find sector 

seekE rr mac-os-error-seekerr 

Drive error (seek) 

si otNumErr mac-os-error-slotnumerr 

Invalid slot number 

spdAdjErr mac-os-error-spdadjerr 

Can't correctly adjust disk speed 

statusErr mac-os-error-statuserr 

Driver can't respond to this Status call 

tkBBadErr mac-os-error-tkObaderr 

Can't find track 

tmfoErr mac-os-error-tmfoerr 

Too many files open 

tmwdoErr mac-os-error-tmwdoerr 

Too many working directories open 

twosi deErr mac-os-error-twosideerr 

Tried to read side 2 of a disk in a single read 

u n i m p E r r mac-os-error-unimperr 

Unimplemented trap 

uni tEmptyErr mac-os-error-unitemptyerr 

Driver reference number specifies NIL handle in unit table 

vLckdErr mac-os-error-vlckderr 

Volume is locked 

volOffLinErr mac-os-error- volof flinerr 

Volume not on-line 

volOnLinErr mac-os-error- volonlinerr 

Specified volume is already mounted and on-line 
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vTypErr mac-os-error-vtyperr 

QType field of entry in vertical retrace queue isn't vType 

viPrErr mac-os-error- wprerr 

Volume is locked by a hardware setting 

wrgUolTypErr mac-os-error- wrgvoltyperr 

Attempt to do hierarchical operation on nonhierarchical volume 

w r i t E r r mac-os-error- writerr 

Driver can't respond to Write calls 

wrPermErr mac-os-error-wrpermerr 

Read/write permission doesn't allow writing 

wrUnderrun mac-os-error- wrunderrun 

Write underrun occurred 



